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Preface 


Intended Audience 

This manual is for programmers at all levels of experience. It covers both user 
interfaces of the debugger: 

• The OpenVMS DECwindows Motif interface for workstations 

• The command interface for terminals and workstations 


4 ^4 


Alpha 


On VAX processors, you can use the debugger with programs written in the 


following VAX languages: 



Ada 

BASIC 

BLISS 

C 

C++ 1 

COBOL 

DIBOL 

FORTRAN 

MACRO-32 

SCAN ♦ 

Pascal 

PL/I 

RPG II 


1 Note that C++ functionality is minimal in this release. 

On Alpha processors, you can use the debugger with programs written in the 


following DEC languages: 



Ada 

BASIC 

BLISS 

c 

C++ 1 

COBOL 

Fortran 

MACRO-32 : 

MACRO-64 

Pascal 

PL/I 



x Note that C++ functionality is minimal in this release. 

2 Note that MACRO-32 must be compiled with the AMACRO compiler. 


The OpenVMS Debugger on OpenVMS Alpha systems can access all the extended 
memory made available by the 64-bit processing of the OpenVMS Alpha operating 
system. Hence, you can examine and manipulate data in the complete 64-bit 
address space. ♦ 

The OpenVMS Debugger has been internationalized. For Asian users, the 
debugger’s DECwindows Motif, command line, and screen mode interfaces can be 
used with multibyte characters. 

You can use the debugger to debug code only in user mode. You cannot debug 
code in supervisor, executive, or kernel modes. 


xxiii 







Document Structure 

This manual is organized as follows: 

• Part I describes the debugger’s DECwindows Motif interface. Part I includes 
the following chapters: 

- Chapter 1 introduces the debugger and gives an overview of its 
DECwindows Motif interface features. 

- Chapter 2 explains how to prepare your program for debugging and then 
start and end a debugging session. 

- Chapter 3, which is organized by task, explains how to use the debugger. 

- Chapter 4, which is organized by task, explains how to use the debugger’s 
Heap Analyzer. 

• Part II describes the debugger’s command interface. Part II includes the 
following chapters: 

- Chapter 5 introduces the command interface. 

- Chapter 6 gets you started using the debugger. 

- Chapter 7 explains how to control and monitor program execution. 

- Chapter 8 explains how to examine and manipulate program data. 

- Chapter 9 explains how to control access to symbols in your program. 

- Chapter 10 explains how to control the display of source code. 

- Chapter 11 explains how to use screen mode. 

- Chapter 12 explains additional convenience features, such as key 
definitions and other customizations. 

- Chapter 13 explains some special cases, such as debugging optimized 
programs and multilanguage programs. 

- Chapter 14 explains how to debug multiprocess programs. 

- Chapter 15 explains how to debug vectorized programs. ♦ 

- Chapter 16 explains how to debug tasking (multithread) programs. 

• Part III is the debugger command dictionary, followed by the appendixes: 

- Appendix A lists the keypad-key definitions that are predefined by the 
debugger. 

- Appendix B identifies all of the debugger built-in symbols and logical 
names. 

- Appendix C identifies the debugger support for languages. 

- Appendix D contains the source code of the programs shown in the figures 
in Chapters 1, 2, and 3. 

Related Documents 

The following documents may also be helpful when using the debugger. 
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Programming Languages 

This manual emphasizes debugger usage that is common to all or most supported 
languages. For more information specific to a particular language, see: 

• The debugger’s online help system (see Section 6.1) 

• The documentation supplied with that language, particularly regarding 
compiling and linking the program for debugging 

• The VAX MACRO and Instruction Set Reference Manual or the MACRO-64 
Assembler for OpenVMS AXP Systems Reference Manual for information 
about assembly-language instructions and the MACRO assembler 

Linker Utility 

For information about the linking of programs or shareable images, see the 
OpenVMS Linker Utility Manual. 

Delta/XDelta Debugger 

For information about debugging code in supervisor, executive, or kernel modes 
(that is, in other than user mode), see the OpenVMS Delta/XDelta Debugger 
Manual in the OpenVMS documentation set. This manual contains information 
about debugging programs that run in privileged processor mode or at an elevated 
interrupt priority level. 

OpenVMS Alpha System-Code Debugger 

On Alpha processors systems, see the OpenVMS Alpha Device Support: 
Developer’s Guide for information on debugging Alpha operating system code. 
This manual describes how to create an Alpha device driver, activate the 
OpenVMS Alpha System-Code Debugger through the OpenVMS Debugger, and 
debug within the OpenVMS Alpha System-Code Debugger environment. 

For information on System-Code Debugger-specific commands, see the CONNECT 
and REBOOT commands in Part III. ♦ 

DECwindows Motif 

For general information about the DECwindows Motif interface, see the VMS 
DECwindows User’s Guide. 

World Wide Web 

For additional information on OpenVMS products and services, access the Digital 
OpenVMS World Wide Web site. Use the following URL: 


http://www.openvms.digital.com 

Reader’s Comments 

Digital welcomes your comments on this manual. 

Print or edit the online form SYS$HELP:OPENVMSDOC_COMMENTS.TXT and 
send us your comments by: 

Internet openvmsdoc@zko.mts.dec.com 

Fax 603 881-0120, Attention: OpenVMS Documentation, ZK03-4/U08 

Mail OpenVMS Documentation Group, ZKO3-4/U08 

110 Spit Brook Rd. 

Nashua, NH 03062-2698 
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How To Order Additional Documentation 

Use the following table to order additional documentation or information. 
If you need help deciding which documentation best meets your needs, call 
800-DIGITAL (800-344-4825). 


Telephone and Direct Mail Orders 


Location 

Call 

Fax 

Write 

U.S.A. 

DECdirect 

800-DIGITAL 

800-344-4825 

Fax: 800-234-2298 

Digital Equipment Corporation 

P.O. Box CS2008 

Nashua, NH 03061 

Puerto Rico 

809-781-0505 

Fax: 809-749-8300 

Digital Equipment Caribbean, Inc. 

3 Digital Plaza, 1st Street, Suite 200 
P.O. Box 11038 

Metro Office Park 

San Juan, Puerto Rico 00910-2138 

Canada 

800-267-6215 

Fax: 613-592-1946 

Digital Equipment of Canada, Ltd. 

Box 13000 

100 Herzberg Road 

Kanata, Ontario, Canada K2K 2A6 

Attn: DECdirect Sales 

International 

— 

— 

Local Digital subsidiary or 
approved distributor 

Internal Orders 

DTN: 264-4446 
603-884-4446 

Fax: 603-884-3960 

U.S. Software Supply Business 

Digital Equipment Corporation 

10 Cotton Road 

Nashua, NH 03063-1260 


ZK-7654A-GE 


Conventions 

The name of the OpenVMS AXP operating system has been changed to OpenVMS 
Alpha. Any references to OpenVMS AXP or AXP are synonymous with OpenVMS 
Alpha or Alpha. 

The following conventions are used to identify information specific to OpenVMS 
Alpha or to OpenVMS VAX: 

The Alpha icon denotes the beginning of information 
specific to OpenVMS Alpha. 

The VAX icon denotes the beginning of information 
specific to OpenVMS VAX. 

The diamond symbol denotes the end of a section of 
information specific to OpenVMS Alpha or to OpenVMS 
VAX. 

In this manual, every use of DECwindows and DECwindows Motif refers to 
DECwindows Motif for OpenVMS software. 

This manual contains many figures showing the DECwindows Motif interface to 
the debugger. Because the display configuration of this interface is customizable, 
these figures may not exactly picture the appearance of debugger displays on 
your system. 


Alpha 


♦ 
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The examples in this manual have not been updated to reflect the fact that the 
OpenVMS Debugger on OpenVMS Alpha systems can access all the extended 
memory made available by the 64-bit processing of the OpenVMS Alpha operating 
system. You should note that hexadecimal addresses are 16-digit numbers on 
Alpha and 8-digit numbers on VAX. For example, 

DBG> EVALUATE/ADDRESS/HEX %hex 000004A0 

00000000000004A0 

DBG> 

♦ 

The following conventions are also used in this manual: 

Ctrl/# A sequence such as Ctrl/# indicates that you must hold down 

the key labeled Ctrl while you press another key or a pointing 
device button. 

PF1 x A sequence such as PF1 # indicates that you must first press 

and release the key labeled PF1 and then press and release 
another key or a pointing device button. 

GOLD x A sequence such as GOLD x indicates that you must first 

press and release the key defined as GOLD and then press 
and release another key. GOLD key sequences can also have 
a slash (/), dash (-), or underscore (_) as a delimiter in EVE 
commands. 

The GOLD key definition is often mapped to the PF1 key on 
the keypad. 

1 Return | In examples, a key name enclosed in a box indicates that 

you press a key on the keyboard. (In text, a key name is not 
enclosed in a box.) 

Horizontal ellipsis points in examples indicate one of the 
following possibilities: 

• Additional optional arguments in a statement have been 
omitted. 

• The preceding item or items can be repeated one or more 
times. 

• Additional parameters, values, or other information can be 
entered. 


Vertical ellipsis points indicate the omission of items from 
a code example or command format; the items are omitted 
because they are not important to the topic being discussed. 

( ) In command format descriptions, parentheses indicate that, if 

you choose more than one option, you must enclose the choices 
in parentheses. 

[ 1 In command format descriptions, brackets indicate optional 

elements. You can choose one, none, or all of the options. 
(Brackets are not optional, however, in the syntax of a directory 
name in an OpenVMS file specification or in the syntax of a 
substring specification in an assignment statement.) 

{ } In command format descriptions, braces surround a required 

choice of options; you must choose one of the options listed. 
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boldface text 


italic text 

UPPERCASE TEXT 

struct 

numbers 


Boldface text represents the introduction of a new term or the 
name of an argument, an attribute, or a reason (user action 
that triggers a callback). 

Boldface text is also used to show user input in Bookreader 
versions of the manual. 

Italic text emphasizes important information and indicates 
complete titles of manuals and variables. Variables include 
information that varies in system messages (Internal error 
number ), in command lines (/PRODUCER=rcarae), and in 
command parameters in text (where device-name contains up 
to five alphanumeric characters). 

Uppercase text indicates a command, the name of a routine, 
the name of a file, or the abbreviation for a system privilege. 

Monospace type in text identifies the following C programming 
language elements: keywords, the names of independently 
compiled external functions and files, syntax summaries, and 
references to variables or identifiers introduced in an example. 

A hyphen at the end of a command format description, 
command line, or code line indicates that the command or 
statement continues on the following line. 

All numbers in text are assumed to be decimal unless 
otherwise noted. Nondecimal radixes—binary, octal, or 
hexadecimal—are explicitly indicated. 


_ Parti 

DECwindows Interface 


This part describes the debugger’s DECwindows Motif interface. 

For information about the debugger’s command interface, see Part II. 
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Introduction to the Debugger: DECwindows 

Motif Interface 

This chapter introduces the debugger’s DECwindows Motif interface. For 
information about the command interface, see Part II. 

This chapter provides the following information: 

• A functional overview of the Open VMS Debugger, including its user interface 
options—DECwindows Motif and command (Section 1.1) 

• An orientation to the debugger’s DECwindows Motif screen features, such as 
windows, menus, and so on (Section 1.2) 

• Instructions for entering debugger commands at the command-entry prompt 
(Section 1.3) 

• Instructions for accessing online help (Section 1.4) 

For information about starting a debugging session, see Chapter 2. For 
information about using the debugger, see Chapter 3. For the source code 
of program EIGHTQUEENS.EXE, shown in the figures of this chapter, see 
Appendix D. 

1.1 Overview of the Debugger 

The Open VMS Debugger helps you locate run-time programming or logic errors, 
also known as bugs. You use the debugger with a program that has been compiled 
and linked successfully, but does not run correctly. For example, the program 
might give incorrect output, go into an infinite loop, or terminate prematurely. 

- Note _ 

You cannot use the DECwindows Motif interface to the debugger to debug 
detached processes such as print symbionts that run without a Command 
line interpreter (CLI). See Section 5.3.8.5 for details about debugging 
detached processes that do not have a CLI. 


You can locate errors with the debugger by observing and manipulating your 
program interactively as it executes. The debugger enables you to: 

• Display the program’s source code and, optionally, your program’s machine- 
level instruction code, as the program executes that code 

• Browse through the source code to identify potential bugs 

• Set breakpoints to suspend program execution at such points 

• Execute the program, one routine at a time, one source line at a time, one 
machine instruction at a time, or from breakpoint to breakpoint 
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• Display the current value of a program variable or register 

• Monitor changes in variables or registers during program execution 

• Change the value of a variable or register and, in some cases, test the 
modification without having to edit and recompile the source code 

As you find errors in the program, you can edit the source code and compile, link, 
and execute the corrected version. 

These are basic debugging techniques. As you use the debugger and its 
documentation, you will discover variations on the basic techniques. You 
can also customize the debugger to your own needs. 

The debugger is a symbolic debugger. You can specify variable names, routine 
names, and symbols precisely as they appear in the source code, or you can 
specify memory addresses and registers when referring to program locations, as 
is most convenient. 

You can use the debugger with programs written in any of the source languages 
listed in the Preface. The debugger recognizes the syntax, data types, operators, 
expressions, scoping rules, and other constructs of the supported languages. 

You can change the debugging context from one language to another during a 
debugging session. 

1.1.1 User Interface Options 

The OpenVMS Debugger has the following user interface options to accommodate 
different needs and debugging styles: 

• The debugger has a character-cell (screen-mode) command interface for 
terminals and workstations. When using this interface, you enter debugger 
commands at a prompt. In addition to general-purpose debugging features, 
the command interface provides special features not available through the 
default DECwindows Motif interface (for example, commands for multiprocess 
debugging). 

• The debugger has a DECwindows Motif interface for workstations. This 
interface is an enhancement to the screen-mode command interface that 
accepts mouse input to choose items from menus and to activate or deactivate 
push buttons, to drag the pointer to select text in windows, and so on. The 
debugger’s DECwindows Motif interface menus and push buttons provide the 
features for most basic debugging tasks. 

The DECwindows Motif interface is layered on the screen-mode command 
interface and has a command-entry prompt on the command line (in the 
command view). From the DECwindows Motif interface command line, you 
can enter debugger commands for the following purposes: 

- As an alternative to using the DECwindows Motif interface menus and 
push buttons for certain operations 

- To do debugging tasks not available through the DECwindows Motif 
interface menus and push buttons 

You can customize the DECwindows Motif interface to associate other 
debugger commands with new or existing pushbuttons. 
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_ Note _ 

The DECwindows Motif interface does not recognize the HELP command 
at its command-entry prompt. Choose the On Commands item in the 
Help menu for online help on debugger commands. 


1-1.2 Convenience Features 

The following paragraphs highlight some of the convenience features of the 
debugger’s default DECwindows Motif interface. Section 1.2 gives visual details. 
(Convenience features of the debugger’s command interface are described in detail 
in Section 5.1.2.) 

Source-Code Display 

The OpenVMS Debugger is a source-level debugger. The debugger displays in 
the source view the source code that surrounds the instruction where program 
execution is paused currently. You can enable and disable the display of compiler¬ 
generated line numbers. 

A source browser lets you: 

• List the images, modules, and routines of your program 

• Display source code from selected modules or routines 

• Display the underlying hierarchy of modules and routines 

• Set breakpoints by double-clicking on selected routines 

Call-Stack Navigation 

The call-stack menu on the main window lists the sequence of routine calls 
currently on the call stack. Click on a routine name in the call-stack menu to set 
(to that routine) the context (scope) for 

• Source code display (in the source view) 

• Register display (in the register view) 

• Instruction display (in the instruction view 

• Symbol searches 

Breakpoints 

You set, activate, and deactivate breakpoints by clicking on buttons next to the 
source lines in the source view or the instruction view. Optionally, you can set, 
deactivate, or activate breakpoints by selecting items in window pull-down menus, 
pop-up menus, context-sensitive menus, or dialog boxes. You can set conditional 
breakpoints, which suspend program execution if the specified condition is true. 
You can set action breakpoints, which execute one or more debugger commands 
when the breakpoint suspends program execution. The main window push 
buttons, the instruction view push buttons, and the breakpoint view give a 
visual indication of activated, deactivated, and conditional breakpoints. 

Push Buttons 

Push buttons in the push button view control common operations: by clicking 
on a push button, you can start execution, step to the next source line, display 
the value of a variable selected in a window, interrupt execution, and so on. 

You can modify, add, remove, and resequence push buttons and the associated 
debugger commands. 
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Context-Sensitive Pop-Up Menus 

Context-sensitive pop-up menus list common operations associated with your 
view (source view, command view, and so on.) When you click MB3, the pop-up 
menu lists actions for the text you have selected, the source line at which you are 
pointing, or the view in which you are working. 

Displaying and Manipulating Data 

To display the value of a variable or expression, select the variable or expression 
in the source view and click on a push button, such as EVAL (evaluate expression) 
or EX (examine variable). You can also display selected values by choosing items 
from window pull-down menus (such as Examine, in the Commands pull-down 
menu), context-sensitive menus, or dialog boxes. You can display values in 
different type or radix formats. 

To change the value of a variable, edit the currently displayed value in the 
monitor view. You can also change values by selecting items in window pull-down 
menus (such as Deposit, in the Commands pull-down menu), context-sensitive 
pop-up menus, or dialog boxes. 

The monitor view displays the updated values of specified variables whenever the 
debugger regains control from your program. 

Kept Debugger RERUN Command 

You can run the debugger in a state known as the kept debugger from which 
you can rerun the same program or run another program without exiting the 
debugger. When rerunning a program, you can choose to save the current state 
of breakpoints, tracepoints, and static watchpoints. The kept debugger is 
also available in the screen mode debugger. See Section 2.1 for information on 
starting the kept debugger. 

Instruction and Register Views 

The instruction view shows the decoded instruction stream (the code that is 
actually executing) of your program. This view is useful if the program you 
are debugging has been optimized by the compiler, in which case the source 
code in the source view may not reflect the code that is executing. You can set 
breakpoints on instructions and display the memory addresses and source-code 
line numbers associated with each instruction. 

The register view displays the current contents of all machine registers. You can 
edit the displayed values to deposit other values into the registers. 

Tasking Program Support 

The tasking view displays information about the current state of all tasks of 
a tasking program (also called a multithread program). You can modify task 
characteristics to control task execution, priority, state transitions, and so on. 

Integration with Command Interface 

The debugger’s DECwindows Motif interface is an enhancement to the screen 
mode debugger. It is layered on, and closely integrated with, the command-driven 
screen mode debugger: 

• When you use the DECwindows Motif interface menus and push buttons, the 
debugger echoes your commands in the command view to provide a record of 
your actions. 

• When you enter commands at the prompt, the debugger updates the 
DECwindows Motif views accordingly. 
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Integration with Source-Level Editor 

You can edit program source code without exiting from the debugger. In the editor 
view, you can display the source code, search and replace text, or add additional 
text. Editor view text buffers allow you to move quickly back and forth between 
new or existing files, and copy, cut, and paste text from buffer to buffer. 

The text editor available through the debugger’s DECwindows Motif menu 
interface is a simple convenience feature, not intended to replace sophisticated 
text editors such as the Language-Sensitive Editor (LSE). To use a different 
editor, enter the Edit command at the DBG> prompt in the command view (see 
EDIT. 

Customization 

You can modify the following and other aspects of the debugger’s DECwindows 
Motif interface and save the current settings in a resource file to customize your 
debugger startup environment: 

• Configuration of windows and views (for example, size, screen location, order) 

• Push button order, labels, and associated debugger commands (this includes 
adding and removing push buttons) 

• Character fonts for displayed text 

Online Help 

Online help is available for the debugger’s DECwindows Motif interface (context- 
sensitive help) and for its command interface. 

1.2 Debugger Windows and Menus 

The following sections describe the debugger windows, menus, views, and other 
features of the Open VMS Debugger DECwindows Motif interface. 

1.2.1 Default Window Configuration 

By default, the debugger starts up in the main window, as shown in Figure 1—1. 

When you start the debugger as explained in Section 2.1, the source view is 
initially empty. Figure 1-1 shows the source view after a program has been 
brought under debugger control (by directing the debugger to run a specific 
image, in this example, EIGHTQUEENS). 

You can customize the startup configuration to your preference as described in 
Section 3.10.1. 

1.2.2 Main Window 

The main window (see Figure 1-1) includes: 

• Title bar (see Section 1.2.2.1) 

• Source view (see Section 1.2.2.2) 

• Pull-down menus (see Section 1.2.2.3) 

• Call Stack view (see Section 1.2.2.4) 

• Push button view (see Section 1.2.2.5) 

• Command view (see Section 1.2.2.6) 
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Figure 1-1 Default Window Configuration 



1.2.2.1 Title Bar 

The title bar, at the top of the main window, displays (by default) the name of the 

debugger, the name of the program being debugged, and the name of the source 

code module that is currently displayed in the source view. 

1.2.2.2 SourceView 

The source view shows the following: 

• Source code of the program you are debugging and, by default, the compiler¬ 
generated line numbers (to the left of the source code). To choose not to 
display line numbers, see Section 3.1. 

• Breakpoint toggle push buttons. 

• Current-location pointer (a triangle to the left of breakpoint push buttons), 
which points to the line of source code that will be executed when program 
execution resumes. 

For more information about displaying source code, see Section 1.2.2.3 and 

Section 3.1. 

1.2.2.3 Menus on Main Window 

Figure 1-2 and Table 1-1 describe the menus on the main window. 


1-6 

























Introduction to the Debugger: DECwindows Motif Interface 

1.2 Debugger Windows and Menus 

Figure 1-2 Menus on Main Window 




Table 1-1 
Menu 

File 


Edit 


Break 


Menus on Main Window 

Item Description 

Run Image... Bring a program under debugger control by specifying 

an executable image. 


Run Foreign 
Command... 

Rerun Same... 

Browse Sources... 

Display Line 
Numbers 

Exit Debugger 

Cut 

Copy 

Paste 

On Exception 

Activate All 
Deactivate All 
Cancel All 


Bring a program under debugger control by specifying 
a symbol for a foreign command. 

Rerun the same program under debugger control. 

Display the source code in any module of your program. 
Set breakpoints on routines. 

Display or hide line numbers in the source view. 


End the debugging session, terminating the debugger. 

Cut selected text and copy it to the clipboard. You can 
cut text only from fields or regions that accept input 
(although, in most cases, Cut copies the selected text to 
the clipboard). 

Copy selected text from the window to the clipboard 
without deleting the text. 

Paste text from the clipboard to a text-entry field or 
region. 

Break on any exception signaled during program 
execution. 

Activate any previously set breakpoints. 

Deactivate any previously set breakpoints. 

Remove all breakpoints from the debugger’s breakpoint 
list and from the breakpoint view. 

(continued on next page) 
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Table 1-1 (Cont.) Menus on Main Window 


Menu 

Item 

Description 


Set... 

Set a new breakpoint, optionally associated with a 
particular condition or action, at a specified location. 

Commands 

Examine... 

Examine the current value of a variable or expression. 
The output value may be typecast or changed in radix. 


Deposit... 

Deposit a value to a variable. The input value may be 
changed in radix. 


Edit File 

Edit the source code of your file in the debugger’s 
editor. 

Options 

Views... 

Display one or more of the following: 



Breakpoint view 

Monitor view 

Register view 

Tasking view 

Instruction view 


Customize 

Buttons... 

Modify, add, remove, or resequence a push button in 
the push button view and the associated debugger 
command. 


Save Options 

Save the current settings of all DECwindows Motif 
features of the debugger that you can customize 
interactively, such as the configuration of windows 
and views, and push button definitions. This preserves 
the current debugger configuration for the next time 
you run the debugger. 


Restore Default 
Options 

Copy the system default debugger resource file 
DECW$SYSTEM_DEFAULTS:VMSDEBUG.DAT 
to the user-specific resource file DECW$USER_ 
DEFAULTS:VMSDEBUG.DAT. The default options 
take effect when you next start the debugger. 


Edit Options File 

Load and display the user-specific resource file 
DECW$USER_DEFAULTS:VMSDEBUG.DAT in the 
debug editor for review and modification. 

Help 

On Context 

Enable the display of context-sensitive online help. 


On Window 

Display information about the debugger. 


On Help 

Display information about the online help system. 


On Version 

Display information about this version of the debugger. 


On Commands 

Display information about debugger commands. 


1.2.2.4 Call Stack Menu 

The Call Stack menu, between the source view and the push button view, shows 
the name of the routine whose source code is displayed in the source view. This 
menu lists the sequence of routine calls currently on the stack and lets you set 
the scope of source code display and symbol searches to any routine on the stack 
(see Section 3.6.2). 
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1.2.2.5 Push Button View 

Figure 1-3 and Table 1-2 describe the default push buttons in the main window. 
You can modify, add, remove, and resequence buttons and their associated 
commands as explained in Section 3.10.3. 


Figure 1-3 Default Buttons in the Push Button View 
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Table 1-2 Default Buttons in the Push Button View 


Button 

Description 

Stop 

Interrupt program execution or a debugger operation without ending the 
debugging session. 

Go 

Start or resume execution from the current program location. 

STEP 

Execute the program one step unit of execution. By default, this is one 
executable line of source code. 

S/in 

When execution is suspended at a routine call statement, move execution 
into the called routine just past the start of the routine. This is the same 
behavior as STEP if not at a routine call statement. 

S/ret 

Execute the program directly to the end of the current routine. 

S/call 

Execute the program directly to the next Call or Return instruction. 

EX 

Display, in the command view, the current value of a variable whose name 
you have selected in a window. 

E/az 

Display, in the command view, the current value of a variable whose 
name you have selected in a window. The variable is interpreted as a 
zero-terminated ASCII string. 

E/ac 

Display, in the command view, the current value of a variable whose name 
you have selected in a window. The variable is interpreted as a counted 
ASCII string preceded by a one-byte count field that contains the length of 
the string. 

EVAL 

Display, in the command view, the value of a language expression in the 
current language (by default, the language of the module containing the 
main program). 

MON 

Display, in the monitor view, a variable name that you have selected in a 
window and the current value of that variable. Whenever the debugger 
regains control from your program, it automatically checks the value and 
updates the displayed value accordingly. 

Command View 


The command view, located directly under the push button view in the main 
window, accepts typed command input on the command line (see Section 1.3), 
and displays debugger output other than that displayed in the optional views. 
Examples of such output are: 

• The result of an Examine operation. 

• Diagnostic messages. For online help on debugger diagnostic messages, see 
Section 1.4.4. 
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• Command echo. The debugger translates your DECwindows Motif menu and 
push button input into debugger commands and displays those commands 
on the command line in the command view, providing a record of your most 
recent commands. This enables you to correlate your input with debugger 
actions. 

You can clear the entire command view, leaving only the current command-line 
prompt, by choosing Clear Command Window from the pop-up menu. 

You can clear the current command line by choosing Clear Command Line from 
the pop-up menu. 

1.2.3 Optional Views Window 

Table 1-3 lists the optional views. They are accessible by choosing Views... from 
the Options menu on the main window. 


Table 1-3 Optional Views 


View 

Description 

Breakpoint view 

List all breakpoints that are currently set and identify those which 
are activated, deactivated, or qualified as conditional breakpoints. The 
breakpoint view also allows you to modify the state of each breakpoint. 

Monitor view 

List variables whose values you want to monitor as your program 
executes. The debugger updates the values whenever it regains control 
from your program (for example, after a step or at a breakpoint). 
Alternatively, you can set a watchpoint, causing execution to stop 
whenever a particular variable has been modified. You can also change 
the values of variables. 

Instruction view 

Display the decoded instruction stream of your program and allow you 
to set breakpoints on instructions. By default, the debugger displays 
the corresponding memory addresses and source-code line numbers to 
the left of the instructions. You can choose to suppress these. 

Register view 

Display the current contents of all machine registers. The debugger 
updates the values whenever it regains control from your program. The 
register view also lets you change the values in registers. 

Tasking view 

List all the existing (nonterminated) tasks of a tasking program. 
Provides information about each task and allows you to modify the 
state of each task. 


Figure 1-5 shows a possible configuration of the breakpoint view, monitor view, 
and register view, as a result of the selections in the View menu in Figure 1-4. 

Figure 1-6 shows the instruction view, which is a separate window so that you 
can position it where most convenient. Figure 1-7 shows the tasking view. 

Note that the registers and instructions displayed are system-specific. Figure 1-5 
and Figure 1-6 show VAX-specific registers and instructions. 

You can move and resize all windows. You can also save a particular configuration 
of the windows and views so that it is set up automatically when you restart the 
debugger (see Section 3.10.1). 
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1.2 Debugger Windows and Menus 


Figure 1-4 Debugger Main Window 
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1.2 Debugger Windows and Menus 

Figure 1-5 Breakpoint, Monitor, and Register Views 



Figure 1-6 Instruction View 
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1.2 Debugger Windows and Menus 


Figure 1-7 Tasking View 


Tasking View 

Task ID 

Priority 

Hold State 

Substate 

Object 

» 1 

7 

RUN 


SHARE$ADARTL+91004 | gj 

2 

7 

SUSP 

I/O or AST 

XT ASK. FATHER H 

3 

6 

READY 


XTASK.MOTHER Q 

4 

7 

SUSP 

Entry call 

XTASK.FATHER TYPE$T*W 


Figure 1-8 Menus on Optional Views Window 
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All 


Abort All Tasks 
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1.2.3.1 Menus on Optional Views Window 

Figure 1-8 and Table 1-4 describe the menus on the optional views window. 
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1.2 Debugger Windows and Menus 


Table 1-4 Menus on Optional Views Window 


Menu 

Item 

Description 

File 

Close 

Close the optional views window. 


Exit Debugger 

End the debugging session, terminating the debugger. 

Break 

On Exception 

Break on any exception signaled during program 
execution. 


Activate All 

Activate any previously set breakpoints. 


Deactivate All 

Deactivate any previously set breakpoints. 


Cancel All 

Remove all breakpoints from the debugger’s breakpoint 
list and from the breakpoint view. 


Toggle 

Toggle a breakpoint. 


Set/Modify... 

Set a new breakpoint, optionally associated with a 
particular condition or action, at a specified location. 


Cancel 

Cancel (delete) an individual breakpoint. 

Monitor 

Expand 

Expand monitor view output to include the values 
of component parts of a selected item as well as the 
aggregate value. 


Collapse 

Collapse the monitor view output to show only the 
aggregate value of a selected item, instead of the values of 
each component part. 


Deposit... 

Change the value of a monitored element. 


Toggle 

Watchpoint 

Toggle a selected watchpoint. 


Typecast 

Use the submenu to typecast output for a selected variable 
to int, long, quad, short, or char*. 


Change Radix 

Use the submenu to change the output radix for a selected 
variable to hex, octal, binary, or decimal. 


Change All Radix 

Use the submenu to change the output radix for all 
subsequent monitored elements to hex, octal, binary, or 
decimal. 


Remove 

Remove an element from the monitor view. 

Register 

Change Radix 

Use the submenu to change radix for selected register to 
hex, octal, binary, or decimal. 


Change All Radix 

Use the submenu to change radix for all registers to hex, 
octal, binary, or decimal. 

Tasks 

Abort 

Request that the selected task be terminated at the next 
allowed opportunity. 


Activate 

Make the selected task the active task. 


Hold 

Place the selected task on hold. 


Nohold 

Release the selected task from hold. 


Make Visible 

Make the selected task the visible task. 


All 

Use the submenu to abort all tasks or release all tasks 
from hold. 

(continued on next page) 
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1.2 Debugger Windows and Menus 


Table 1-4 (Cont.) Menus on Optional Views Window 


Menu 

Item 

Description 

Options 

Views... 

Display one or more of the following: 



Breakpoint view 

Monitor view 

Register view 

Tasking view 

Instruction view 


Customize 

Buttons... 

Modify, add, remove, or resequence a push button in the 
push button view and the associated debugger command. 


Save Options 

Save the current settings of all DECwindows Motif 
features of the debugger that you can customize 
interactively, such as the configuration of windows and 
views, and push button definitions. This preserves your 
current debugger configuration for the next time you run 
the debugger. 


Restore Default 
Options 

Copy the system default debugger resource file 
DECW$SYSTEM_DEFAULTS:VMSDEBUG.DAT 
to the user-specific resource file DECW$USER 
DEFAULTS:VMSDEBUG.DAT. The default options take 
effect when you next start the debugger. 


Edit Options File 

Load and display the user-specific resource file 
DECW$USER_DEFAULTS:VMSDEBUG.DAT in the 
debug editor for review and modification. 

Help 

On Context 

Enable the display of context-sensitive online help. 


On Window 

Display information about the debugger. 


On Help 

Display information about the online help system. 


On Version 

Display information about this version of the debugger. 


On Commands 

Display information about debugger commands. 


1.3 Entering Commands at the Prompt 

The debugger’s DECwindows Motif interface is layered on the command interface. 
The command line, the last line in the command view and identified by the 
command-entry prompt (DBG>), lets you enter debugger commands for the 
following purposes: 

• As an alternative to using the DECwindows Motif interface menus and push 
buttons for certain operations 

• To do debugging tasks not available through the DECwindows Motif interface 
pull-down menus and push buttons 

Figure 1—9 shows the RUN command in the command view. 
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Figure 1-9 Entering Commands at the Prompt 


0 stop 

lOGol 

|sTEp| 

|s/in| 

|s/ret| 

|s/call| 

[ex| 

||E/az| 

|E/ac| 

|eval] 

|mon| 




A 


OpenVMS VAX DEBUG Version V7.0-000 


DBG> run eightqueens 

Language: C, Module: EIGHTQUEENS 

Type GO to reach MAIN program 

No source line for address: 0000C4E7 

DBG> 



When you use the DECwindows Motif interface pull-down menus and push 
buttons, the debugger translates your input into debugger commands and 
echoes these commands on the command line so that you have a record of your 
commands. Echoed commands are visually indistinguishable from commands 
that you enter explicitly on the command line. 

For information about the debugger’s command interface, see Part II. For online 
help about the commands, see Section 1.4.3. 

In addition to entering debugger commands interactively at the prompt, you can 
also place them in debugger initialization files and command files for execution 
within the DECwindows Motif environment. 

You can also take advantage of the keypad support available at the command- 
entry prompt. (This support is a subset of the more extensive keypad support 
provided for the command interface, which is described in Appendix A.) The 
commands in Table 1-5 are mapped to individual keys on your computer 
keypad. 


Table 1-5 Keypad Definitions in the DECwindows Motif Debugger Interface 


Command 

Corresponding Key 

Step/Line 

KPO 

Step/Into 

GOLD-KPO 

Step/Over 

BLUE-KPO 

Examine 

KP1 

Examine A 

GOLD-KP1 

Go 

KP, 

Show Calls 

KP5 

Show Calls 3 

GOLD-KP5 


To enter one of these commands, press the key or keys indicated, followed by the 
Enter key on the keypad. (The GOLD key is PF1; the BLUE key is PF4.) 

For information on changing these key bindings, or binding commands to 
unassigned keys on the keypad, see Section 3.10.4.4. 
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1.3 Entering Commands at the Prompt 

1.3.1 Debugger Commands That Are Not Available in the DECwindows Motif 
Interface 

Table 1-6 lists the debugger commands that are disabled in the debugger’s 
DECwindows Motif interface. Many of them are relevant only to the debugger’s 
screen mode. 

Table 1-6 Debugger Commands not Available in the DECwindows Motif 
Interface 


ATTACH 

SELECT 

CANCEL MODE 

(SET,SHOW) ABORT_KEY 

CANCEL WINDOW 

(SET,SHOW) KEY 

DEFINE/KEY 

(SET,SHOW) MARGINS 

DELETE/KEY 

SET MODE [NO]KEYPAD 

DISPLAY 

SET MODE [NOJSCREEN 

EXAMINE/SOURCE 

SET MODE [NOJSCROLL 

EXPAND 

SET OUTPUT [NOJTERMINAL 

EXTRACT 

(SET,SHOW) TERMINAL 

HELP 1 

(SET,SHOW) WINDOW 

MOVE 

(SET,CANCEL) DISPLAY 

SAVE 

SHOW SELECT 

SCROLL 

SPAWN 


^elp on commands is available from the Help menu in a debugger window. 


The debugger issues an error message if you enter any of these commands on 
the command line, or if the debugger encounters one of these commands while 
executing a command procedure. 

1.4 Displaying Online Help About the Debugger 

The following types of online help about the debugger and debugging are 
available during a debugging session: 

• Context-sensitive help—information about an area or object in a window or 
dialog box 

• Task-oriented help—consists of an introductory help topic named Overview of 
the Debugger and several subtopics on specific debugging tasks 

• Help on debugger commands and various topics, such as language support 

• Help on debugger diagnostic messages 

Task-oriented topics related to context-sensitive topics are connected through the 
list of additional topics in the help windows. 
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1.4.1 Displaying Context-Sensitive Help 

Context-sensitive help is information about an area or object in a window or a 
dialog box. 

To display context-sensitive help: 

1. Choose On Context from the Help menu in a debugger window. The pointer 
shape changes to a question mark (?). 

2. Place the question mark on an object or area in a debugger window or dialog 
box. 

3. Click MB1. Help for that area or object is displayed in a Help window. 
Additional topics provide task-oriented discussions, where applicable. 

To display context-sensitive help for a dialog box, you can also click on the Help 
button in the dialog box. 

_ Note _ 

You cannot get true context-sensitive help about any push button other 
than Stop. This is because all other buttons can be modified or removed. 


1.4.2 Displaying the Overview Help Topic and Subtopic 

The Overview help topic (Overview of the Debugger) and its subtopics provide 
task-oriented information about the debugger and debugging. 

To display the Overview topic, use either of these techniques: 

• Choose On Window from the Help menu in a debugger window. 

• Choose Go To Overview from the View menu of a debugger help window. 

To display information about a particular topic, choose it from the list of 
additional topics. 

1.4.3 Displaying Help on Debugger Commands 

To display help on debugger commands: 

1. Choose On Commands from the Help menu of a debugger window. 

2. Choose the command name or other topic (for example, Language_Support) 
from the list of additional topics. 

Note that the Help command is not available through the command view. 

1.4.4 Displaying Help on Debugger Diagnostic Messages 

Debugger diagnostic messages are displayed in the command view. To display 
help on a particular message: 

1. Choose On Commands from the Help menu of a debugger window. 

2. Choose Messages from the list of additional topics. 

3. Choose the message identifier from the list of additional topics. 
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Starting and Ending a Debugging Session 


This chapter explains how to: 

• Start the debugger (Section 2.1) 

• Continue when your program completes execution (Section 2.2) 

• Rerun the same program from the current debugging session (Section 2.3) 

• Run another program from the current debugging session (Section 2.4) 

• Interrupt program execution and debugger operations (Section 2.5) 

• End a debugging session (Section 2.6) 

• Start the debugger in additional ways for specific purposes (Section 2.7) 

2.1 Starting the Debugger 

This section explains the most common way to start the debugger from DCL level 
($) and bring your program under debugger control. Section 2.7 explains optional 
ways to start the debugger. 

Starting the kept debugger as explained here enables you to use the Rerun (see 
Section 2.3) and Run (see Section 2.4) features. 

To start the debugger and bring your program under debugger control: 

1. Verify that you have compiled and linked the program as explained in 
Section 5.2. 

2. Verify that the debugging configuration (default or multiprocess) 
is appropriate for the kind of program you are going to debug (see 
Section 5.3.8.3). For a program that runs in only one process (the typical 
case), use the default configuration. 

3. Enter the following command line: 

$ DEBUG/KEEP 

By default, the debugger starts up as shown in Figure 2-1. The main window 
remains empty until you bring a program under debugger control (step 4). 
Upon startup, the debugger executes any user-defined initialization file (see 
Section 12.2). 
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Figure 2-1 Debugger at Startup 



4. Bring your program under debugger control using one of the following two 
techniques: 

• Run a specified image (this is the most common technique): 

1. Choose Run Image... from the File menu on the main window. The 
Run Image dialog box lists the executable images in your current 
directory (see Figure 2-2). 

2. Click on the name of the image to be debugged. The Image: field 
displays the image name. 

3. If applicable, enter arguments to be passed to the program in the 
Arguments: field. If you specify a quoted string, you might have to 
add quotation marks because the debugger strips quotes when parsing 
the string. 

4. Click on OK. 

• Run an image by specifying a DCL command or a symbol for a foreign 

command: 

1. Choose Run Foreign Command... from the File menu on the main 
window. The Run Foreign Command dialog box is displayed (see 
Figure 2-3). 

2. Enter the symbol in the Foreign Command: field (such a symbol can 
provide a shortcut around the directory and file selection process). 

The foreign command XI, shown in Figure 2-3, has been previously 
defined: 

$X1 :== RUN MYDISK:[MYDIRECTORY.MYSUBDIRECTORYJEIGHTQUEENS.EXE 

3. Enter any arguments to be passed with the command in the 
Arguments: field. 
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Figure 2-2 Running a Program by Specifying an Image 
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File Edit Break Commands 


Run Image. 
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DBG> 


i= 


Debug: Run Image 
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DISK:[USER]*.exe 


Directories 


Images 


DISK:[USER] 


8Q.EXE; 1 

DBG_ECHOARGS.EXE; 1 
DBG_EIGHTQUEENS.EXE; 1 
ECHOARGS.EXE;3 


EIGHTQUEENS.EXE;7 


MOREQUEENS.EXE; 1 


Arguments: 


□ Heap Analyzer 


Image : 


DISK:[USER] EIGHTQUEENS.EXE; 7 


OK 


Filter 


Cancel 


Help 


Figure 2-3 Running a Program by Specifying a Command Symbol 
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Exit Debugger 


JHelp | 


Debug: Run Foreign Command 


Foreign Command: 
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XI 


□ Heap Analyzer 


OK 


Cancel 


Help 


4. Click on OK. 

Once the debugger has control of the program, the debugger: 

• Displays the program’s source code in the main window, as shown in 
Figure 2-4. 
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2.1 Starting the Debugger 


• Suspends execution at the start of the main program. The current-location 
pointer to the left of the source code, shows which line of code will be executed 
next. 

Figure 2-4 Source Display at Startup 



The message displayed in the command view indicates that this debugging 
session is initialized for a C program and that the name of the source module is 
EIGHTQUEENS. 

With certain programs, the debugger sets a temporary breakpoint to suspend 
program execution at the start of some initialization code, before the main 
program, and displays the following message: 

Type GO to reach MAIN program 
No source line for address: nnnnnnnn 

With some of these programs (for example, Ada programs), the breakpoint 
enables you to debug the initialization code using full symbolic information. 

The initialization sets up language-dependent debugger parameters. These 
parameters control the way the debugger parses names and expressions, formats 
debugger output, and so on. 

You can now debug your program as explained in Chapter 3. 

Note the following restrictions about running a program under debugger control: 

• You cannot use the procedure in this section to connect the debugger to a 
running program (see Section 2.7.2). 

• You cannot run a program under debugger control over a DECnet link. Both 
the image to be debugged and the debugger must reside on the same node. 
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2.2 When Your Program Completes Execution 

When your program completes execution normally during a debugging session, 

the debugger issues the following message: 

'Normal successful completion' 

You then have the following options: 

• You can rerun your program from the same debugging session (see 
Section 2.3). 

• You can run another program from the same debugging session (see 
Section 2.4). 

• You can end the debugging session (see Section 2.6). 

2.3 Rerunning the Same Program from the Current Debugging 
Session 

You can rerun the program currently under debugger control at any time during 

a debugging session, provided you originally started the debugger as explained in 

Section 2.1. 

To rerun your program: 

1. Choose Rerun Same... from the File menu on the main window. The Rerun 
dialog box is displayed (see Figure 2-5). 

2. Enter any arguments to be passed to the program, if required, in the 
Arguments: field. If you specify a quoted string, you might have to add 
quotation marks because the debugger strips quotes when parsing the string. 

3. Choose whether or not to keep the current state of any breakpoints, 
tracepoints, or static watchpoints that you previously set, activated, or 
deactivated (see Section 3.4 and Section 3.5.5). Nonstatic watchpoints might 
or might not be saved, depending on the scope of the variable being watched 
relative to the main program unit (where execution restarts). 

4. Click on OK. 


Figure 2-5 Rerunning the Same Program 


OpenVMS Debug64 - EIGHTQUEENS: EIGHTQUEENS 


File 


Edit Break Commands Options 
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Starting and Ending a Debugging Session 

2.3 Rerunning the Same Program from the Current Debugging Session 


When you rerun a program, it is in the same initial state as a program that is 
brought under debugger control as explained in Section 2.1, except for any saved 
breakpoints, tracepoints, or static watchpoints. The source display and current 
location pointer are updated accordingly. 

When you rerun a program, the debugger uses the same version of the image 
that is currently under debugger control. To debug a different version of that 
program (or a different program) from the same debugging session, choose Run 
Image... or Run Foreign Command., from the File menu on the main window 
(see Section 2.1). 

2.4 Running Another Program from the Current Debugging Session 

You can bring another program under debugger control at any time during a 
debugging session, if you started the debugger as explained in Section 2.1. Follow 
the procedure in that section for bringing a program under debugger control (also 
note the restrictions about using that procedure). 

2.5 Interrupting Program Execution and Aborting Debugger 
Operations 

To interrupt program execution during a debugging session, click on the Stop 
button on the push button view (see Figure 1-3). This is useful if, for example, 
the program is in an infinite loop. 

To abort a debugger operation in progress, click on Stop. This is useful if, for 
example, the debugger is displaying a long stream of data. 

Clicking on Stop does not end the debugging session. Clicking on Stop has no 
effect when the program is not running or when the debugger is not executing a 
command. 

2.6 Ending a Debugging Session 

To end a debugging session and terminate the debugger, choose Exit Debugger 
from the File menu on the main window, or enter EXIT at the prompt (to avoid 
confirmation dialog). This returns control to system level. 

To rerun your program from the current debugging session, see Section 2.3. 

To run another program from the current debugging session, see Section 2.4. 

2.7 Additional Options for Starting the Debugger 

In addition to the startup procedure described in Section 2.1, the following 
options are available for starting the debugger from DCL level ($): 

• Start the debugger by running the program to be debugged with the DCL 
RUN command (see Section 2.7.1). 

• Interrupt a running program by pressing Ctrl/Y and then start the debugger 
using the DCL DEBUG command (see Section 2.7.2). 

• Establish a default or multiprocess debugging configuration to debug a 
program that runs in either one or several processes, respectively (see 
Chapter 16). 

• Override the debugger’s default (DECwindows Motif) interface (see 
Section 2.7.3) to achieve the following: 

- Display the DECwindows Motif interface on another workstation 
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- Display the command interface in a DECterm window along with any 
program input/output (I/O) 

- Display the command interface and program I/O in separate DECterm 
windows 

In all cases, before starting the debugger, verify that you have compiled and 
linked the modules of your program (as explained in Section 5.2) and established 
the proper debugging configuration (as explained in Section 5.3.8.3). 

2.7.1 Starting the Debugger by Running a Program 

You can start the debugger and also bring your program under debugger control 
in one step by entering the DCL command RUN program-image (assuming the 
program was compiled and linked with the /DEBUG qualifier). 

However, you cannot then use the Rerun or Run features explained in Section 2.3 
and Section 2.4, respectively. To rerun the same program or run a new program 
under debugger control, you must first exit the debugger and start it again. 

To start the debugger by running a program, enter the DCL command 
RUN program-image to start the debugger. For example: 

$ RON EIGHTQUEENS 

By default, the debugger starts up as shown in Figure 2-4, executing any user- 
defined initialization file and displaying the program’s source code in the main 
window. The current-location pointer shows that execution is paused at the start 
of the main program. The debugger sets the language-dependent parameters to 
the source language of the main program unit. 

For more information about debugger startup, see Section 2.1. 

2.7.2 Starting the Debugger After Interrupting a Running Program 

You can bring a program that is executing freely under debugger control. T his is 
useful if you suspect that the program might be in an infinite loop or if you see 
erroneous output. 

To bring your program under debugger control: 

1. Enter the DCL command RUN/NODEBUG program-image to execute the 
program without debugger control. 

2. Press Ctrl/Y to interrupt the executing program. Control passes to the DCL 
command interpreter. 

3. Enter the DCL command DEBUG to start the debugger. 

For example: 

$ RUN/NODEBUG EIGHTQUEENS 


[Ctri/Y] 

Interrupt 
$ DEBUG 

[starts debugger] 

At startup, the debugger displays the main window and executes any user-defined 
initialization file, and sets the language-dependent parameters to the source 
language of the module in which execution was interrupted. 
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To help you determine where execution was interrupted: 

1. Look at the main window. 

2. Enter the SET MODULES/CALLS command at the command-entry prompt. 

3. Display the Call Stack menu on that window to identify the sequence of 
routine calls on the call stack. The routine at level 0 is the routine in which 
execution is currently paused (see Section 3.3.1). 

When you start the debugger in this manner, you cannot then use the Rerun or 
Run features explained in Section 2.3 and Section 2.4, respectively. To rerun the 
same program or run a new program under debugger control, you must first exit 
the debugger and start it again. 

For more information about debugger startup, see Section 2.1. 

2.7.3 Overriding the Debugger’s Default Interface 

By default, if your workstation is running DECwindows Motif, the debugger 
starts up in the DECwindows Motif interface, which is displayed on the 
workstation specified by the DECwindows Motif applicationwide logical name 
DECW$DISPLAY. 

This section explains how to override the debugger’s default DECwindows Motif 
interface to achieve the following: 

• Display the debugger’s DECwindows Motif interface on another workstation 

• Display the debugger’s command interface in a DECterm window along with 
any program I/O 

• Display the debugger’s command interface and program I/O in separate 
DECterm windows 

The logical name DBG$DECW$DISPLAY enables you to override the 
default interface of the debugger. In most cases, there is no need to define 
DBG$DECW$DISPLAY because the default is appropriate. 

Section 2.7.3.4 provides more information about the logical names 
DBG$DECW$DISPLAY and DECW$DISPLAY. 

2.7.3.1 Displaying the Debugger’s DECwindows Motif Interface on Another Workstation 

If you are debugging a DECwindows Motif application that uses most of the 
screen (or if you are debugging pop-ups in a Motif application), you might find 
it useful to run the program on one workstation and display the debugger’s 
DECwindows Motif interface on another. To do so: 

1. Enter a logical definition with the following syntax in the DECterm window 
from which you plan to run the program: 

DEFINE/JOB DBG$DECW$DISPLAY workstationpathname 

The path name for the workstation where the debugger’s DECwindows Motif 
interface is to be displayed is workstation pathname. See the description of 
the SET DISPLAY command in the OpenVMS DCL Dictionary for the syntax 
of this path name. 

It is recommended that you use a job definition. If you use a process 
definition, it must not have the CONFINE attribute. 
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2. Run the program from that DECterm window. The debugger’s DECwindows 
Motif interface is now displayed on the workstation specified by 
DBG$DECW$DISPLAY. The application’s windowing interface is displayed on 
the workstation where it is normally displayed. 

2.7.3.2 Displaying the Debugger’s Command Interface in a DECterm Window 

To display the debugger’s command interface in a DECterm window, along with 
any program I/O: 

1. Enter the following definition in the DECterm window from which you plan 
to start the debugger: 

$ DEFINE/JOB DBG$DECW$DISPLAY " " 

You can specify one or more spaces between the quotation marks. It is 
recommended that you use a job definition for the logical name. If you use a 
process definition, it must not have the CONFINE attribute. 

2. Start the debugger from that DECterm window (see Section 2.1). The 
debugger’s command interface is displayed in the same window. 

For example: 

$ DEFINE/JOB DBG$DECW$DISPLAY " " 

$ DEBOG/KEEP 

Debugger Banner and Version Number 

DBG> 

You can now bring your program under debugger control as explained in 
Section 2.1. 

2.7.3.3 Displaying the Command Interface and Program Input/Output in Separate DECterm 
Windows 

This section describes how to display the debugger’s command interface in a 
DECterm window other than the DECterm window in which you start the 
debugger. This separate window is useful when using the command interface to 
debug a screen-oriented program as follows: 

• The program’s input/output (I/O) is displayed in the window from which you 
start the debugger. 

• The debugger’s I/O, including any screen-mode display, is displayed in the 
separate window. 

The effect is the same as entering the SET MODE SEPARATE command at the 
DBG> prompt on a workstation running VWS rather than DECwindows Motif. 
(The SET MODE SEPARATE command is not valid when used in a DECterm 
window.) 

The following example shows how to display the debugger’s command interface in 
a separate debugger window titled Debugger. 

1. Create the command procedure SEPARATE_WINDOW.COM shown in 
Example 2-1. 
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Example 2-1 Command Procedure SEPARATE_WINDOW.COM 

$ ! Simulates effect of SET MODE SEPARATE from a DECterm window 
$ ! 

$ CREATE/TERMINAL/NOPROCESS - 

/WINDOW_ATTRIBUTES=(TITLE="Debugger",- 
ICON_NAME="Debugger", ROWS=40)- 
/DEFINE_LOGICAL=(TABLE=LNM$JOB,DBG$INPUT,DBGSOUTPUT) 

$ ALLOCATE DBG$OUTPUT 
$ EXIT 
$ ! 

$ ! The command CREATE/TERMINAL/NOPROCESS creates a DECterm 
$ ! window without a process. 

$ ! 

$ ! The /WINDOW_ATTRIBUTES qualifier specifies the window's 
$ ! title (Debugger), icon name (Debugger), and the number 
$ ! of rows in the window (40). 

$ ! 

$ ! The /DEFINE_LOGICAL qualifier assigns the logical names 
$ ! DBG$INPUT and DBG$OUTPUT to the window, so that it becomes 
$ ! the debugger input and output device. 

$ ! 

$ ! The command ALLOCATE DBGSOUTPUT causes the separate window 
$ ! to remain open when you end the debugging session. 

2. Execute the command procedure as follows: 

$ @SEPARATE_WINDOW 

%DCL-I-ALLOC, _MYN0DE$TWA8: allocated 

A new DECterm window is created with the attributes specified in 
SEPARATE_WINDOW.COM. 

3. Follow the steps in Section 2.7.3.2 to display the debugger’s command 
interface. The interface is displayed in the new window. 

4. You can now enter debugger commands in the debugger window. Program I/O 
is displayed in the DECterm window from which you started the debugger. 

5. When you end the debugging session with the EXIT command, control returns 
to the DCL prompt in the program I/O window but the debugger window 
remains open. 

6. To display the debugger’s command interface in the same window as the 
program’s I/O (as in Section 2.7.3.2), enter the following commands: 

$ DEASSIGN/JOB DBG$INPUT 
$ DEASSIGN/JOB DBG$OUTPUT 

The debugger window remains open until you close it explicitly. 

2.7.3.4 Explanation of DBG$DECW$DISPLAY and DECW$DISPLAY 

By default, if your workstation is running DECwindows Motif, the debugger 
starts up in the DECwindows Motif interface, which is displayed on the 
workstation specified by the DECwindows Motif applicationwide logical name 
DECW$DISPLAY. DECW$DISPLAY is defined in the job table by FileView or 
DECterm and points to the display device for the workstation. 

For information about DECW$DISPLAY, see the description of the DCL 
commands SET DISPLAY and SHOW DISPLAY in the OpenVMS DCL Dictionary. 
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The logical name DBG$DECW$DISPLAY is the debugger-specific equivalent 
of DECW$DISPLAY. DBG$DECW$DISPLAY is similar to the debugger-specific 
logical names DBG$INPUT and DBG$OUTPUT. These logical names enable you 
to reassign SYS$INPUT and SYS$OUTPUT, respectively, to specify the device on 
which debugger input and output are to appear. 

The default user interface of the debugger results when DBG$DECW$DISPLAY 
is undefined or has the same translation as DECW$DISPLAY. By default, 
DBG$DECW$DISPLAY is undefined. 

The algorithm that the debugger follows when using the logical definitions of 
DECW$DISPLAY and DBG$DECW$DISPLAY is as follows: 

1. If the logical name DBG$DECW$DISPLAY is defined, then use it. Otherwise, 
use the logical name DECW$DISPLAY. 

2. Translate the logical name. If its value is not null (if the string contains 
characters other than spaces), the DECwindows Motif interface is displayed 
on the specified workstation. If the value is null (if the string consists only of 
spaces), the command interface is displayed in the DECterm window. 

To enable the Open VMS debugger to startup in the DECwindows Motif interface, 
first enter one of the following DCL commands: 

$DEFINE DBG$DECW$DISPLAY "WSNAME::0" 

$SET DISPLAY/CREATE/NODE=WSNAME 

where WSNAME is the nodename of your workstation. 
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Using the Debugger 


This chapter explains how to: 

• Display the source code of your program (Section 3.1) 

• Edit your program under debugger control (Section 3.2) 

• Execute your program under debugger control (Section 3.3) 

• Suspend execution with breakpoints (Section 3.4) 

• Examine and manipulate program variables (Section 3.5) 

• Access program variables (Section 3.6) 

• Display and modify values stored in registers (Section 3.7) 

• Display the decoded instruction stream of your program (Section 3.8) 

• Debug tasking programs (Section 3.9) 

• Customize the debugger’s DECwindows Motif interface (Section 3.10) 

The chapter describes window actions and window menu choices, but you can 
perform most common debugger operations by choosing items from context- 
sensitive pop-up menus. To access these menus, click MB3 while the mouse 
pointer is in the window area. 

You can also enter commands at the DECwindows Motif command prompt. For 
information about entering debugger commands, see Section 1.3. 

For the source code of programs EIGHTQUEENS.EXE and 8QUEENS.EXE, 
shown in the figures of this chapter, see Appendix D. 

3.1 Displaying the Source Code of Your Program 

The debugger displays the source code of your program in the main window (see 
Figure 3-1). 

Whenever execution is suspended (for example, at a breakpoint), the debugger 
updates the source display by displaying the code surrounding the point at which 
execution is paused. The current-location pointer, to the left of the source code, 
marks which line of code will execute next. (A source line corresponds to one or 
more programming-language statements, depending on the language and coding 
style.) 

By default, the debugger displays compiler-generated line numbers to the left 
of the source code. These numbers help you identify breakpoints that are listed 
in the breakpoint view (see Section 3.4.4). You can choose not to display line 
numbers so that more of the source code can show in the window. To hide or 
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Figure 3-1 Source Display 



display line numbers, choose Display Line Numbers from the File menu on the 
main window. 

The Call Stack menu, between the source view and the push button view, shows 
the name of the routine whose source code is displayed. 

The current-location pointer is normally filled in as shown in Figure 3-1. It 
is cleared if the displayed code is not that of the routine in which execution is 
paused (see Section 3.1.3 and Section 3.6.2). 

You can use the scroll bars to show more of the source code. However, you can 
scroll vertically through only one module of your program at a time. (A module 
corresponds generally to a compilation unit. With many programming languages, 
a module corresponds to the contents of a source file. With some languages, such 
as Ada, a source file might contain one or more modules.) 

The following sections explain how to display source code for other parts of 
your program so that you can set breakpoints in various modules, and so on. 
Section 3.1.3 explains what to do if the debugger cannot find source code for 
display. Section 3.6.2 explains how to display the source code associated with 
routines that are currently active on the call stack. 

After navigating the main window, you can redisplay the location at which 
execution is paused by clicking on the Call Stack menu. 

If your program was optimized during compilation, the source code displayed 
might not reflect the actual contents of some program locations (see Section 5.2). 

3.1.1 Displaying Source Code of Another Routine 

To display source code of another routine: 

1. Choose Browse Sources... from the File menu on the main window (see 
Figure 3-2). The Source Browser dialog box displays the name of your 
executable image, which is highlighted, and all the shareable images linked 
with it (for example, DEBUG and LIBRTL). The name of a linked image is 
dimmed if no symbolic information is available for that image. 

2. Double click on the name of your executable image. The names of the 
modules in that image are displayed (indented) under the image name. 

3. Double click on the name of the module containing the routine of interest. 
The names of the routines in that module are displayed (indented) under the 
module name, and the Display Source button is now highlighted. 
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4. Click on the name of the routine whose source code you want to display. 

5. Click on the Display Source push button. The debugger displays in the source 
view the source code of the target routine, along with an empty breakpoint 
button to the left of the source code. If instruction view is open, this display 
is updated to show machine code of the target routine. 

Section 3.6.2 describes an alternative way to display routine source code for 
routines currently active on the call stack. 

Figure 3-2 Displaying Source Code of Another Routine 
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3.1.2 Displaying Source Code of Another Module 

To display source code of another module: 

1. Choose Browse Sources... from the File menu on the main window. The 
Source Browser dialog box displays the name of your executable image, which 
is highlighted, and all the shareable images linked with it (for example, 
DEBUG and LIBRTL). The names of the shareable images are dimmed if no 
symbolic information is available for them. 

2. Double click on the name of your executable image. The names of the 
modules in that image are displayed (indented) under the image name. 

3. Click on the name of the module whose source code you want to display. The 
Display Source button is now highlighted. 

4. Click on Display Source. The source display in the main window now shows 
the routine’s source code. (If the instruction display in the instruction view is 
open, this display is updated to show the routine’s instruction code.) 

3.1.3 Making Source Code Available for Display 

In certain cases, the debugger cannot display source code. Possible causes are: 

• Execution might be paused within a module of your program that was 
compiled or linked without the debug option (see Section 5.2). 

• Execution might, be paused within a system or library routine for which 
no symbolic information is intended to be available. In such cases you can 
quickly return execution to the calling routine by clicking one or more times 
on the S/ret button in the push button view (see Section 3.3.5). 

• The source file might have been moved to a different directory after it was 
compiled. Section 3.1.4 explains how to tell the debugger where to look for 
source files. 

If the debugger cannot find source code for display, it tries to display the source 
code for the next routine down on the call stack for which source code is available. 
If the debugger can display source code for such a routine, the current-location 
pointer is cleared and marks the source line to which execution returns in the 
calling routine. 

3.1.4 Specifying the Location of Source Files 

Information about the characteristics and the location of source files is embedded 
in the debug symbol table of your program. If a source file has been moved to a 
different directory since compile time, the debugger might not find the file. To 
direct the debugger to your source files, use the SET SOURCE command at the 
DBG> prompt (see Section 10.2). 

3.2 Editing Your Program 

The debugger provides a simple text editor you can use to edit your source files 
while debugging your program (see Figure 3-3). 

The text editor available through the debugger’s DECwindows Motif menu 
interface is a simple convenience feature, not intended to replace sophisticated 
text editors such as the Language-Sensitive Editor (LSE). You cannot substitute 
a more sophisticated editor for the text editor invoked with the Edit File item in 
the Commands menu. To use a different editor, enter the Edit command at the 
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DBG> prompt in the command view (see the description of the EDIT command in 
Part III of this manual). 

Figure 3-3 Editor Window 



To invoke the editor, choose the Edit File item in the Commands menu on the 
main window. By default, the editor opens a buffer and displays the module 
currently displayed in the source view. The buffer is named with the file 
specification of the file in the buffer. If no file is displayed in the source view, the 
editor displays an empty text buffer, called main_buffer. The buffer name appears 
in the buffer menu, which is just under the menu bar of the editor view. 

The editor allows you to create any number of text buffers by choosing New (for 
empty text buffers) or Open (for existing files) from the File menu. The name of 
each text buffer appears in the buffer menu. You can cut, copy, and paste text 
from buffer to buffer by choosing items from the Edit menu and selecting buffers 
from the buffer menu. 

You can perform forward and backward search and replace operations by entering 
strings in the Find and Replace with fields and clicking on a directional arrow. 
You can perform a repeated search for the string by continuing to press the 
Return key. You can also continue a search by choosing the Find/Replace Next or 
Find/Replace Previous items in the Edit menu. 

To save the file, choose the Save or Save As... items from the File menu. If you do 
not save your corrections before closing a modified buffer or exiting the debugger, 
the debugger displays a warning message. 

To test any changes to the source code: 

1. Select a DEC term window separate from that in which the debugger is 
running. 

2. Recompile the program. 

3. Relink the program. 
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4. Return to the debugging session. 

5. Choose the Run Image... item in the File menu on the main window. 

3.3 Executing Your Program 

This section explains how to: 

• Determine where execution is currently paused within your program 

• Start or resume program execution 

• Execute the program one source line at a time, step by step 

For information about rerunning your program or running another program from 
the current debugging session, see Section 2.3 and Section 2.4. 

3.3.1 Determining Where Execution Is Currently Paused 

To determine where execution is currently paused within your program: 

1. If the current-location pointer is not visible in the main window, click on the 
Call Stack menu of that window to display the pointer (see Figure 3-1). 

2. Look at the current-location pointer: 

• If the pointer is filled in, it marks the source line whose code will execute 
next (see Section 3.1). The Call Stack menu always shows the routine at 
scope level 0 (where execution is paused) when the pointer is filled in. 

• If the pointer is cleared, the source code displayed is that of a calling 
routine, and the pointer marks the source line to which execution returns 
in that routine: 

- If the Call Stack menu shows level 0, source code is not available for 
display for the routine in which execution is paused (see Section 3.1.3). 

- If the Call Stack menu shows a level other than 0, you are displaying 
the source code for a calling routine (see Section 3.6.2). 

To list the sequence of routine calls that are currently active on the call stack, 
click on the Call Stack menu. Level 0 denotes the routine in which execution is 
paused, level 1 denotes the calling routine, and so on. 

3.3.2 Starting or Resuming Program Execution 

To start program execution or resume execution from the current location, click 
on the Go button in the push button view (see Figure 1-3). 

Letting your program run freely without debugger intervention is useful in 
situations such as the following: 

• To test for an infinite loop. In this case, you start execution; then, if your 
program does not terminate and you suspect that it is looping, click on the 
Stop button. The main window will show where you interrupted program 
execution, and the Call Stack menu will identify the sequence of routine calls 
at that point (see Section 3.3.1). 

• To execute your program directly to a particular location. In this case, 
you first set a breakpoint at the location (see Section 3.4) and then start 
execution. 
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Once started, program execution continues until one of the following events 
occurs: 

• The program completes execution. 

• A breakpoint is reached (including a conditional breakpoint whose condition 
is true). 

• A watchpoint is triggered. 

• An exception is signaled. 

• You click on the Stop button on the push button view. 

Whenever the debugger suspends execution of the program, the main window 
display is updated and the current-location pointer marks which line of code will 
execute next. 

3.3.3 Executing Your Program One Source Line at a Time 

To execute one source line of your program, click on the STEP button in the push 
button view or enter the STEP command in the command view. This debugging 
technique (called stepping) is one of the most commonly used. 

After the line executes, the source view is updated and the current-location 
pointer marks which line of code will execute next. 

Note the following points about source lines and the stepping behavior: 

• A source line can consist of one or more programming language elements 
depending on the language and coding style used. 

• When you click on the STEP button, the debugger executes one executable 
line and suspends execution at the start of the next executable line, skipping 
over any intervening nonexecutable lines. 

• Executable lines are those for which instructions were generated by the 
compiler (for example, lines with routine call or assignment statements). 
Executable lines have a button to their left in the main window. 

• Examples of nonexecutable lines are comment lines or lines with variable 
declarations without value assignments. Nonexecutable lines do not have a 
button to their left in the main window. 

Keep in mind that if you optimized your code at compilation time, the source code 
displayed might not reflect the code that is actually executing (see Section 5.2). 

3.3.4 Stepping into a Called Routine 

When program execution is paused at a routine call statement, clicking on the 
STEP button typically executes the called routine in one step (depending on 
the coding style used), and the debugger suspends execution at the next source 
line in the calling routine (assuming no breakpoint was set within the called 
routine). This enables you to step through the code quickly without having to 
trace execution through any called routines (some of which might be system or 
library routines). This is called stepping over called routines. 

To step into a called routine so that you can execute it one line at a time: 

1. Suspend execution at the routine call statement, for example, by setting a 
breakpoint (see Section 3.4) and then clicking on the Go button in the push 
button view. 
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2. When execution is paused at the call statement, click on the S/in button 
in the push button view, or enter the STEP/INTO command at the DBG> 
prompt. This moves execution just past the start of the called routine. 

Once execution is within the called routine, click on the STEP button to execute 
the routine line by line. 

Clicking on the S/in button when execution is not paused at a routine call 
statement is the same as clicking on the STEP button. 

3.3.5 Returning from a Called Routine 

When execution is suspended within a called routine, you can execute your 
program directly to the end of that routine by clicking on the S/ret button in the 
push button view, or enter the STEP/RETURN command at the DBG> prompt. 

The debugger suspends execution just before the routine’s return instruction 
executes. At that point, the routine’s call frame has not been deleted from the call 
stack, so you can still get the values of variables local to that routine, and so on. 

You can also use the S/call button in the push button view (or enter the STEP 
/CALL command at the DBG> prompt) to execute the program directly to the 
next Return or Call instruction. 

The S/ret button is particularly useful if you have inadvertently stepped into a 
system or library routine (see Section 3.1.3). 

3.4 Suspending Execution by Setting Breakpoints 

A breakpoint is a location in your program at which you want execution to stop so 
that you can check the current value of a variable, step into a routine, and so on. 

When using the debugger’s DECwindows Motif interface, you can set breakpoints 
on: 

• Specific source lines 

• Specific routines (functions, subprograms, and so on) 

• Exceptions signaled during the execution of your program 
The debugger provides two ways to qualify breakpoints: 

• You can set a conditional breakpoint. It triggers only when a specified 
relational expression is evaluated as true. 

• You can set an action breakpoint. It executes one or more specified 
system-specific commands when the breakpoint triggers. 

You can set a breakpoint that is both a conditional and action breakpoint. 

The following sections explain these breakpoint options. 

3.4.1 Setting Breakpoints on Source Lines 

You can set a breakpoint on any source line that has a button to its left in 
the source display. These are the lines for which the compiler has generated 
executable code (routine declarations, assignment statements, and so on). 

To set a breakpoint on a source line: 

1. Find the source line on which you want to set a breakpoint (see Section 3.1). 
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2. Click on the button to the left of that line. (The breakpoint is set when the 
button is filled in.) The breakpoint is set at the start of the source line—that 
is, on the first machine-code instruction associated with that line. 

Figure 3-4 shows that a breakpoint has been set on the start of line 37. 

Figure 3-4 Setting a Breakpoint on a Source Line 



3.4.2 Setting Breakpoints on Routines with Source Browser 

Setting a breakpoint on a routine enables you to move execution directly to the 

routine and inspect the local environment. 

To set a breakpoint on a routine: 

1. Choose Browse Sources... from the File menu on the main window (see 
Figure 3-2). The Source Browser dialog box displays the name of your 
executable image, which is highlighted, and all the shareable images linked 
with it (for example, DEBUG and LIBRTL). The name of a linked image is 
dimmed if no symbolic information is available for that image. 

2. Double click on the name of the executable image. The names of the modules 
in that image are displayed (indented) under the image name. 

3. Double click on the name of the target module. The names of the routines 
in that module are displayed (indented) under the module name (see 
Figure 3-5). 

4. Double click on the name of the routine on which to set a breakpoint. The 
debugger echoes the results of your SET BREAKPOINT command on the 
command line in the command view. 

Alternatively, click once on the name of the routine, then click the Set 
Breakpoint button in the Source Browser view. The debugger echoes the 
results of your SET BREAKPOINT command on the command line in the 
command view. 
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Figure 3-5 Setting a Breakpoint on a Routine 



3.4.3 Setting an Exception Breakpoint 

An exception breakpoint suspends execution when an exception is signaled and 
before any exception handler declared by your program executes. This enables 
you to step into the exception handler (if one is available) to check the flow of 
control. 

To set an exception breakpoint, choose On Exception from the Break menu on the 
main window or the optional views window. The exception breakpoint triggers 
whenever any exception is signaled. 

3.4.4 Identifying the Currently Set Breakpoints 

There are three ways to determine which breakpoints are currently set: 

• Scroll through your source code and note the lines whose breakpoint button is 
filled in. This method can be time consuming and also does not show which 
breakpoints were set and then deactivated (see Section 3.4.5). 

• Choose the Views... item from the Options menu on the main window or 
the optional views window. When the Views dialog box appears, click on 
breakpoint view to display the breakpoint view (see Figure 1-4). 

The breakpoint view lists a module name and line number for each breakpoint 
(see Section 3.1). A filled-in button next to the breakpoint identification 
indicates that the breakpoint is activated. A cleared button indicates that the 
breakpoint is deactivated. 
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• Enter the SHOW BREAK command at the DBG> prompt in the command 
view. The debugger list all the breakpoints that are currently set, including 
trigger conditions for conditional breakpoints, and commands to be executed 
by action breakpoints. 

3.4.5 Deactivating, Activating, and Canceling Breakpoints 

After a breakpoint is set, you can deactivate, activate, or delete it. 

Deactivating a breakpoint causes the debugger to ignore the breakpoint during 
program execution. However, the debugger keeps the breakpoint listed in the 
breakpoint view so that you can activate it at a later time, for example, when you 
rerun the program (see Section 2.3). Note the following points: 

• To deactivate a specific breakpoint, clear the button for that breakpoint in the 
main window or in the breakpoint view. 

In the breakpoint view, you can also choose Toggle from the Break menu, if 
the breakpoint is currently activated. 

• To deactivate all breakpoints, choose Deactivate All from the Break menu. 
Activating a breakpoint causes it to take effect during program execution: 

• To activate a breakpoint, fill in the button for that breakpoint in the main 
window or in the breakpoint view. 

In the breakpoint view, you can also choose Toggle from the Break menu, if 
the breakpoint is currently deactivated. 

• To activate all breakpoints, choose Activate All from the Break menu. 

When you cancel a breakpoint, it is no longer listed in the breakpoint view so 
that later you cannot activate it from that list. You have to reset the breakpoint 
as explained in Section 3.4.1 and Section 3.4.2. Note the following points: 

• To cancel a specific breakpoint, choose Cancel from the Break menu on the 
optional views window. 

• To cancel all breakpoints, choose Cancel All from the Break menu. 

3.4.6 Setting a Conditional Breakpoint 

A conditional breakpoint suspends execution only when a specified expression 
is evaluated as true. For example, you can specify that a breakpoint take effect 
when the value of a variable in your program is 4. The breakpoint is ignored if 
the value is other than 4. 

The debugger evaluates the conditional expression when the breakpoint triggers 
during execution of your program. 

The following procedure sets a conditional breakpoint, whether or not a 
breakpoint was previously set at that location: 

1. Display the source line on which you want to set the conditional breakpoint 
(see Section 3.1). 

2. Do one of the following: 

• Press Ctrl/MBl on the button to the left of the source line. This displays 
the Set/Modify Breakpoint dialog box, showing the source line you selected 
in the Location: field (see Figure 3-6). 
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• Choose the Set or Set/Modify item from the Break menu. When the 
Set/Modify Breakpoint dialog box displays, enter the source line in the 
Location field. 


3. Enter a relational expression in the Condition: field of the dialog box. The 
expression must be valid in the source language. For example, a[3] == 0 is a 
valid relational expression in the C language. 

4. Click on OK. The conditional breakpoint is now set. The debugger indicates 
that a breakpoint is conditional by changing the shape of the breakpoint’s 
button from a square to a diamond. 


Figure 3-6 Setting a Conditional Breakpoint 


P 7 ] OpenVMS Debug64 - EIGHTQUEENS: EIGHTQUEENS 


File Edit Break Commands Options 



44 


45 

□ 

46 


47 


48 


49 

□ 

50 


Help 


void setqueen(m, j) 
int m; 
int j; 

{ 

a[m] = 0; 
b[m + j] = 0; 


Debug: Set/Modify Breakpoint 


>stop|| o Go ||sTE p||s/i n||s/ret||s/cal 


OK 


stepped to EIGHTQUEENS\tryc o 
DBG> step 

stepped to EIGHTQUEENS\tryco 
DBG> step 

stepped to EIGHTQUEENS\tryco 
DBG> SET BREAK EIGHTQUEENS\%LINE 49 WHEN (a[m] 
DBG> 


Location: 

Condition: 

Action: 


EIGHTQUEENSYfcLINE 49 


a[m] 


□ Activate/Deactivate Breakpoint 


Apply 


Delete Breakpoint 


Cancel 


Help 


IB 


H 


The following procedure modifies a conditional breakpoint; that is, it can be 
used to change the location or condition associated with an existing conditional 
breakpoint, or to change an unqualified breakpoint into a conditional breakpoint: 

1. Choose the Views... item from the Options menu on the main window 
or optional views window. When the Views dialog box appears, click on 
breakpoint view to display the breakpoint view. 


2. From the breakpoint view, do one of the following: 

• Press Ctrl/MBl on the button to the left of the listed breakpoint. 

• Click on a breakpoint listed in the view, and choose the Set/Modify item 
from the Break menu. 

3. Follow steps 3 and 4 of the previous procedure, as appropriate. 
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3.4.7 Setting an Action Breakpoint 

When an action breakpoint triggers, the debugger suspends execution and then 

executes a specified list of commands. 

To set an action breakpoint, whether or not a breakpoint was previously set at 

that location: 

1. Display the source line on which you want to set the action breakpoint (see 

Section 3.1). 

2. Do one of the following: 

• Press Ctrl/MBl on the button to the left of the source line. This displays 
the Set/Modify Breakpoint dialog box, showing the source line you selected 
in the Location: field (see Figure 3-6). 

• Choose the Set or Set/Modify item from the Break menu. When the 
Set/Modify Breakpoint dialog box displays, enter the source line in the 
Location: field. 

3. Enter one or more debugger commands in the Action: field of the dialog box. 

For example: DEPOSIT x[j] = 3; STEP; EXAMINE a 

4. Click on OK. The action breakpoint is now set (see Figure 3-7.) 


Figure 3-7 Setting an Action Breakpoint 
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The following procedure modifies an action breakpoint; that is, it can be used to 
change the location or command associated with an existing action breakpoint, or 
to change an unqualified breakpoint into an action breakpoint: 


3-13 























































Using the Debugger 

3.4 Suspending Execution by Setting Breakpoints 


1. Choose the Views... item from the Options menu on the main window or 
optional views window, then click on Breakpoints when the Views dialog box 
appears. 

2. From the breakpoint view, do one of the following: 

• Press Ctrl/MBl on the button to the left of the listed breakpoint. 

• Click on a breakpoint listed in the view, and choose the Set/Modify item 
in the Break menu. 

3. Follow steps 3 and 4 of the previous procedure, as appropriate. 

3.5 Examining and Manipulating Variables 

This section explains how to: 

• Select variable names from windows 

• Display the value of a variable 

• Monitor a variable 

• Watch a variable 

• Change the value of a variable 

See Section 3.6, which also applies to all operations on variables. 

3.5.1 Selecting Variable Names from Windows 

Use the following techniques to select variable names from windows for the 
operations described in the sections that follow (see Section 3.5.2 for examples). 

When selecting names, follow the syntax of the source programming language: 

• To specify a scalar (nonaggregate) variable, such as an integer, real, Boolean, 
or enumeration type, select the variable’s name. 

• To specify an entire aggregate, such as array or structure (record), select the 
variable’s name. 

• To specify a single element of an aggregate variable, select the entity using 
the language syntax. For example: 

- The string arr2 [7] specifies element 7 of array arr2 in the C language. 

- The string employee.address specifies component address of record 
(structure) employee in the Pascal language. 

• To specify the object designated by a pointer variable, select the entity 
following the language syntax. For example, in the C language, the string 
*int_point specifies the object designated by pointer int_point. 

Select character strings from windows as follows: 

• In any window, to select a string delimited by blank spaces, use the standard 
DECwindows Motif word selection technique: position the pointer on that 
string and then double click MB1. 

• In any window, to select an arbitrary character string, use the standard 
DECwindows Motif text-selection technique: position the pointer on the first 
character, press and hold MB1 while dragging the pointer over the string and 
then release MB1. 
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• In the debugger source display, you also have the option of using language- 
sensitive text selection. To select a string delimited by language-dependent 
identifier boundaries, position the pointer on that string and press 
Ctrl/MBl. 

For example, suppose the source display contains the character string 
arr2 [m] , then: 

- To select arr2, position the pointer on arr2 and press Ctrl/MBl. 

- To select m, position the pointer on m and press Ctrl/MBl. 

You can change the key sequence for language-sensitive text selection as 
explained in Section 3.10.4.2. 

3.5.2 Displaying the Current Value of a Variable 

To display the current value of a variable: 

1. Find and select the variable name in a window as explained in Section 3.5.1. 

2. Click on the EX button in the push button view. The debugger displays the 
variable and its current value in the command view. The debugger displays 
the value of a variable in the current scope, which might not be the same as 
the source location you were intending. 

Figure 3—8, Figure 3—9, and Figure 3—10 show how to display the value of an 
integer variable, array aggregate, and array element, respectively. 

Figure 3-8 Displaying the Value of an Integer Variable 



To display the current value in a different type or radix, use the following 
alternative method: 

1. Find and select the variable name in a window as explained in Section 3.5.1. 
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Figure 3-9 Displaying the Value of an Array Aggregate 



Figure 3-10 Displaying the Value of an Array Element 



2. Choose the Examine... item in the Commands menu in the main window. The 
Examine dialog box appears with the name selected in the 
Variable/Expression field. 

3. Choose the default, int, long, quad, short, or char* item from the Typecast 
menu within the dialog box. 
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4. Choose the default, hex, octal, decimal, or binary item from the Output Radix 
menu within the dialog box. 

5. Click on OK. 

The value, altered to your specification, appears in the command view. 

Figure 3—11 shows that the variable j has been typecast as long. 

Figure 3-11 Typecasting the Value of a Variable 



3.5.3 Changing the Current Value of a Variable 

To change the current value of a variable: 

• Find and select the variable name in a window as explained in Section 3.5.1. 

• Choose the Deposit... item from the Commands menu in the main window. 
The Deposit dialog box appears with the name selected in the Variable field. 

• Enter the new value in the Value field. 

• Choose the default, hex, octal, decimal, or binary item from the Input Radix 
menu within the dialog box. 

• Click on OK. 

The new value, altered to your specification, appears in the command view and is 
assigned to the variable. 

Figure 3-12 shows a new value for the variable safe. 

Figure 3-12 Changing the Value of a Variable 
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3.5.4 Monitoring a Variable 

When you monitor a variable, the debugger displays the value in the monitor 
view and checks and updates the displayed value whenever the debugger regains 
control from your program (for example, after a step or at a breakpoint). 

__ Note - 

You can monitor only a variable, including an aggregate such as an array 
or structure (record). You cannot monitor a composite expression or 
memory address. 


To monitor a variable (see Figure 3-13): 

1. Find and select the variable name in a window as explained in Section 3.5.1. 

2. Click on the MON button in the push button view. The debugger: 

• Displays the monitor view (if it is not displayed) 

• Puts the selected variable’s name, along with its qualifying path name, in 
the Monitor Expression column 

• Puts the value of the variable in the Value/Deposit column 

• Puts a cleared button in the Watched column (see Section 3.5.5). 

You can typecast the output value when monitoring variables by choosing the 
Typecast item in the Monitor menu. 

You can change the output radix when monitoring variables as follows: 

• Choose the Change Radix item in the Monitor menu to change the output 
radix for a selected monitored element. 

• Choose the Change All Radix in the Monitor menu to change the output radix 
for all subsquently monitored elements. 

To remove a monitored element from the monitor view, choose the Remove item 
from the Monitor menu. 

3.5.4.1 Monitoring an Aggregate (Array or Structure) Variable 

If you select the name of an aggregate variable, such as an array or structure 
(record) and click on the MON button, the debugger displays the word Aggregate 
in the Value/Deposit column of the Monitor View. To display the values of all 
elements (components) of an aggregate variable, double click on the variable 
name in the Monitor Expression column (or choose the Expand item in the 
Monitor menu). The displayed element names are indented relative to the parent 
name (see Figure 3-14). If an element is also an aggregate, you can double click 
on its name to display its elements, and so on. 
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Figure 3-13 Monitoring a Variable 
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Figure 3-14 Expanded Aggregate Variable (Array) in Monitor View 
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To collapse an expanded display so that only the aggregate parent name is shown 
in the monitor view, double click on the name in the Monitor Expression column 
(or choose the Collapse item from the Monitor menu). 


If you have selected a component of an aggregate variable, and the component 
expression is itself a variable, the debugger monitors the component that 
was active when you made the selection. For example, if you select the array 
component arr [i] and the current value of i is 9, the debugger monitors arr [9] 
even if the value of i subsequently changes to 10. 
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3.5.4.2 Monitoring a Pointer (Access) Variable 

If you select the name of a pointer (access) variable and click on the MON button, 
the debugger displays the address of the referenced object in the 
Value/Deposit column of the monitor view (see the top entry in Figure 3-15). 

To monitor the value of the referenced object (to dereference the pointer variable), 
double click on the pointer name in the Monitor Expression column. This adds 
an entry for the referenced object in the monitor view, indented under the pointer 
entry (see the bottom entry in Figure 3-15). If a referenced object is an aggregate, 
you can double click on its name to display its elements, and so on. 

Figure 3-15 Pointer Variable and Referenced Object in Monitor View 



3.5.5 Watching a Variable 

Whenever the program changes the value of a watched variable, the debugger 

suspends execution and displays the old and new values in the command view. 

To watch a variable (also known as setting a watchpoint on a variable): 

• Monitor the variable as explained in Section 3.5.4. The debugger puts a 
button in the Watched column of the monitor view whenever you monitor a 
variable. See Figure 3-16. 

• Click on the button in the Watched column. A filled-in button indicates that 
the watchpoint is set. 


Figure 3-16 Watched Variable in Monitor View 



To deactivate a watchpoint, clear its Watched button in the monitor view (by 
clicking on the button) or choose the Toggle Watchpoint item in the Monitor 
menu. To activate a watchpoint, fill in its Watched button or choose the Toggle 
Watchpoint item in the Monitor menu. 
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Section 3.6.1 explains static and nonstatic (automatic) variables and how to 
access them. The debugger deactivates a nonstatic watchpoint when execution 
moves out of (returns from) the variable’s defining routine. When a nonstatic 
variable is no longer active, its entry is dimmed in the monitor view and its 
Watched button is cleared. 

The debugger does not automatically reactivate nonstatic watchpoints if execution 
later returns to the variable’s defining routine. You must reactivate nonstatic 
watchpoints explicitly. 

3.5.6 Changing the Value of a Monitored Scalar Variable 

To change the value of a scalar (nonaggregate) variable, such as an integer or 
Boolean type (see Figure 3-17): 

1. Monitor the variable as explained in Section 3.5.4. 

2. Click on the variable’s value in the Value/Deposit column of the monitor view. 
A small dialog box is displayed over that value, which you can now edit. 

3. Enter the new value in the dialog box. 

4. Click on the check mark (OK) in the dialog box. The dialog box is removed 
and replaced by the new value, indicating that the variable now has 
that value. The debugger notifies you if you try to enter a value that is 
incompatible with the variable’s type, range, and so on. 

Figure 3-17 Changing the Value of a Monitored Scalar Variable 



To cancel a text entry and dismiss the dialog box, click on X (Cancel). 

You can change the value of only one component of an aggregate variable (such 
as an array or structure) at a time. To change the value of an aggregate-variable 
component (see Figure 3-18): 

1. Display the value of the component as explained in Section 3.5.4.1. 

2. Follow the previous procedure for changing the value of a scalar variable. 

3.6 Accessing Program Variables 

This section provides some general information about accessing program variables 
while debugging. 

If your program was optimized during compilation, you might not have access to 
certain variables while debugging. When you compile a program for debugging, it 
is best to disable optimization, if possible (see Section 5.2). 
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Figure 3-18 Changing the Value of a Component of an Aggregate Variable 



Before you check on the value of a variable, always execute the program beyond 
the point where the variable is declared and initialized. The value contained in 
any uninitialized variable should be considered invalid. 

3.6.1 Accessing Static and Nonstatic (Automatic) Variables 

_ Note_ 

The generic term nonstatic variable is used here to denote what is 
called an automatic variable in some languages. 


A static variable is associated with the same memory address throughout 
execution of the program. You can always access a static variable. 

A nonstatic variable is allocated on the stack or in a register and has a value 
only when its defining routine or block is active (on the call stack). Therefore, you 
can access a nonstatic variable only when program execution is paused within 
the scope of its defining routine or block (which includes any routine called by the 
defining routine). 

A common technique for accessing a nonstatic variable is first to set a breakpoint 
on the defining routine and then to execute the program to the breakpoint. 

Whenever the execution of your program makes a nonstatic variable inaccessible, 
the debugger notifies you as follows: 

• If you try to display the value of the variable or monitor the variable (as 
explained in Section 3.5.2 and Section 3.5.4, respectively), the debugger issues 
a message that the variable is not active or not in scope. 

• If the variable (or an expression that includes the variable) is currently being 
monitored, its entry becomes dimmed in the monitor view. When the entry 
is dimmed, the debugger does not check or update the variable’s displayed 
value; also, you cannot change that value as explained in Section 3.5.3. The 
entry is fully displayed whenever the variable becomes accessible again. 

• If the variable is currently being watched (as explained in Section 3.5.5), 
the watchpoint is deactivated (its Watched button is cleared) and its entry 
is dimmed in the monitor view. However, note that the watchpoint is not 
reactivated automatically when the variable becomes accessible again. 
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3.6.2 Setting the Current Scope Relative to the Call Stack 

While debugging a routine in your program, you can set the current scope to a 
calling routine (a routine down the stack from the routine in which execution is 
currently paused). This enables you to: 

• Determine where the current routine call originated 

• Determine the value of a variable declared in a calling routine 

• Determine the value of a variable during a particular invocation of a routine 
that is called recursively 

• Change the value of a variable in the context of a routine call 

The Call Stack menu on the main window lists the names of the routines (and, 
under certain conditions, the images and modules) of your program that are 
currently active on the stack, up to the maximum number of lines that can be 
displayed on your screen (see Figure 3-19). The numbers on the left side of the 
menu indicate the level of each routine on the stack relative to level 0, which 
denotes the routine in which execution is paused. 

To set the current scope to a particular routine on the stack, choose the routine’s 
name from the Call Stack menu (see Figure 3-19). This causes the following to 
occur: 

• The Call Stack menu, when released, shows the name and relative level of 
the routine that is now the current scope. 

• The main window shows that routine’s source code. 

• The instruction view (if displayed) shows that routine’s decoded instructions. 

• The register view (if displayed) shows the register values associated with that 
routine call. 

• If the scope is set to a calling routine (a call-stack level other than 0), the 
debugger clears the current-location pointer, as shown in Figure 3-19. 

• The debugger sets the scope for symbol searches to the chosen routine, so that 
you can examine variables, and so on, in the context of that scope. 

When you set the scope to a calling routine, the current-location pointer (which 
is cleared) marks the source line to which execution will return in that routine. 
Depending on the source language and coding style used, this might be the line 
that contains the call statement or some subsequent line. 

3.6.3 How the Debugger Searches for Variables and Other Symbols 

Symbol ambiguities can occur when a symbol (for example, a variable name X) is 
defined in more than one routine or other program unit. 

In most cases, the debugger automatically resolves symbol ambiguities. First, 
it uses the scope and visibility rules of the currently set language. In addition, 
because the debugger permits you to specify symbols in arbitrary modules (to set 
breakpoints and so on), the debugger uses the ordering of routine calls on the call 
stack to resolve symbol ambiguities. 
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Figure 3-19 Current Scope Set to a Calling Routine 



In some cases, however, the debugger might respond as follows when you specify 

a symbol that is defined multiple times: 

• It might issue a "symbol not unique" message because it is not able to 
determine the particular declaration of the symbol that you intended. 

• It might reference the symbol declaration that is visible in the current scope, 
not the one you want. 

To resolve such problems, you must specify a scope where the debugger should 

search for the particular declaration of the symbol: 

• If the different declarations of the symbol are within routines that are 
currently active on the call stack, use the Call Stack menu on the main 
window to reset the current scope (see Section 3.6.2). 

• Otherwise, enter the appropriate command at the command prompt 
(EXAMINE or MONITOR, for example), specifying a path-name prefix 
with the symbol. For example, if the variable X is defined in two modules 
named COUNTER and SWAP, the following command uses the path name 
SWAPXX to specify the declaration of X that is in module SWAP: 

DBG> EXAMINE SWAP\X 
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3.7 Displaying and Modifying Values Stored in Registers 

The register view displays the current contents of all machine registers (see 
Figure 3-20). 

To display the register view, choose the Views... item from the Options menu on 
the main window or the optional views window, then click on Registers when the 
Views dialog box appears. 

By default the register view automatically displays the register values associated 
with the routine in which execution is currently paused. Any values that change 
as your program executes are highlighted whenever the debugger regains control 
from your program. 

To display the register values associated with any routine on the call stack, choose 
its name from the Call Stack menu on the main window (see Section 3.6.2). 

To change the value stored in a register: 

1. Click on the register value in the register view. A small dialog box is 
displayed over the current value, which you can now edit. 

2. Enter the new value in the dialog box. 

3. Click on the check mark (OK) in the dialog box. The debugger removes 
the dialog box and displays the new value, indicating that the register now 
contains that value. To dismiss the dialog box without changing the value in 
the register, click on X (Cancel). 

To change the radix used to display register values: 

• Choose the Change Radix item in the Register menu to change the radix in 
current and subsequent output for a selected register. 

• Choose the Change All Radix item in the Register menu to change the radix 
in current and subsequent output for all registers. 

Figure 3-20 Register View 
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3.8 Displaying the Decoded Instruction Stream of Your Program 

The instruction view displays the decoded instruction stream of your program: 
the code that is actually executing (see Figure 3-21). This is useful if the 
program you are debugging has been optimized by the compiler so that the 
information in the main window does not exactly reflect the code that is executing 
(see Section 5.2). 


Figure 3-21 Instruction View 



To display the instruction view, choose the Views... item from the Options menu 
on the main window or the optional views window, then click on Instructions 
when the Views dialog box appears. 

By default, the instruction view automatically displays the decoded instruction 
stream of the routine in which execution is currently paused. The current- 
location pointer, to the left of the instructions, marks the instruction that will 
execute next. 

By default, the debugger displays source code line numbers to the left of the 
instructions with which they are associated. To hide or display line numbers, 
toggle Display Line Numbers from the File menu in the instruction view. 

By default, the debugger displays memory addresses to the left of the 
instructions. To hide or display addresses, toggle Show Instruction Addresses 
from the File menu in the instruction view. 

After navigating the instruction view, click on the Call Stack menu to redisplay 
the location at which execution is paused. 

To display the instruction stream of any routine on the call stack, choose the 
routine’s name from the Call Stack menu on the main window (see Section 3.6.2). 

3.9 Debugging Tasking Programs 

Tasking programs have multiple threads of execution within a process and 
include the following: 

• Programs in any language that uses DECthreads or POSIX 1003.1b services. 

• Programs that use language-specific tasking services (services provided 
directly by the language). Currently, Ada is the only language with built-in 
tasking services that the debugger supports. 
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Within the debugger, the term task denotes such a flow of control, regardless of 
the language or implementation. The debugger’s tasking support applies to all 
such programs. 

The debugger enables you to display task information and modify task 
characteristics to control task execution, priority, state transitions, and so 
on. 

The following sections summarize the tasking features of the debugger’s 
DEC windows Motif interface. For more information about the debugger’s tasking 
support, see Chapter 16. 

3.9.1 Displaying Information About Tasks 

To display information about one or more tasks of your program, choose the 
Views... item from the Options menu on the main window or the optional views 
window, then click on Tasking when the Views dialog box appears. 

The tasking view gives information about all currently existing (nonterminated) 
tasks of your program. The information is updated whenever the debugger 
regains control from the program, as shown in Figure 3-22. 

Figure 3-22 Tasking View 
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The displayed information includes: 

• The task ID. The arrow in the left column marks the active task: the task 
that runs when you click on the Go or Step button. 

• The task priority. 

• Whether the task has been put on hold as explained in Section 3.9.2. 

• The current state of the task. The task in the RUN (running) state is the 
active task. 

• The current substate of the task. The substate helps indicate the possible 
cause of a task’s state. 

• A debugger path name for the task (thread) object or the address of the task 
object if the debugger cannot symbolize the task object. 
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3.9 Debugging Tasking Programs 


3.9.2 Changing Task Characteristics 

To modify a task’s characteristics or the tasking environment while debugging, 
choose one of the following items from the Tasks menu. 


Tasks Menu Item 

Description 

Abort 

Request that the selected task be terminated at the next 
allowed opportunity. The exact effect depends on the current 
event facility (language dependent). For Ada tasks, this is 
equivalent to executing an abort statement. 

Activate 

Make the selected task the active task. 

Hold 

Place the selected task on hold. 

Nohold 

Release the selected task from hold. 

Make Visible 

Make the selected task the visible task. 

All 

Use the submenu to abort all tasks or release all tasks from 
hold. 


3.10 Customizing the Debugger’s DECwindows Motif Interface 

The debugger is installed on your system with a default debugger resource 
file (DECW$SYSTEM_DEFAULTS:VMSDEBUG.DAT) that defines the startup 
defaults for the following customizable parameters: 

• Configuration of windows and views 

• Whether to show or hide line numbers in the main window 

• Button names and associated debugger commands 

• Key sequence to display the dialog box for conditional and action breakpoints 

• Key sequence for language-sensitive text selection in the source view and 
instruction view 

• Character fonts for text in the views 

• Character font for text displayed in specific windows and views 

• Color of the text foreground and background colors in the source view, 
instruction view, and editor view 

• Display of program, module, and routine names in the main window title bar 

• Whether or not the debugger requires confirmation before exiting 

A copy of the system default debugger resource file with explanatory comments is 
included in Example 3-1. 

You can modify the first three of these display attributes interactively from the 
DECwindows Motif interface, as explained in Section 3.10.1, Section 3.10.2, and 
Section 3.10.3. In each case, you can save the modified display configuration for 
future debugging sessions by choosing Save Options from the Options menu. 

In addition, you can modify all the listed attributes of the debugger display 
configuration by editing and saving the debugger resource file, as explained in 
Section 3.10.4. 
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When you choose Save Options from the Options menu or you edit and save 
the local debugger resource file, the debugger creates a new version of the 
local debugger resource file DECW$USER_DEFAULTS:VMSDEBUG.DAT that 
contains the definitions of the display configuration attributes. When you next 
start the debugger, it uses the attributes defined in the most recent local resource 
file to configure the output display. You can fall back to previous debugger display 
configurations with appropriate use of the DCL DELETE, RENAME, and COPY 
commands. 

To fall back to the system default display configuration, select Restore Default 
Options from the OpenVMS debugger Options menu. 

3.10.1 Defining the Startup Configuration of Debugger Views 

To define the startup configuration of the debugger views: 

1. While using the debugger, set up your preferred configuration of views. 

2. Choose Save Options from the Options menu to creates a new version of the 
debugger resource file. 

When you next start the debugger, the debugger uses the most recent resource 
file to create the new display configuration. 

You can also define the startup display configuration by editing the definition of 
these views in the resource file (see Section 3.10.4). 

3.10.2 Displaying or Hiding Line Numbers in Source View and Instruction View 

The source view and instruction views display source line numbers by default at 
debugger startup. To hide (or display) line numbers at debugger startup: 

1. While using the debugger, choose Display Line Numbers from the File menu 
on the main (or instruction) window. Line numbers are displayed when a 
filled-in button appears next to that menu item. 

2. Choose Save Options from the Options menu to create a new version of the 
debugger's local resource file. 

When you next start the debugger, the debugger uses the most recent resource 
file to create the new display configuration. 

You can also set the startup default for line numbers by setting the following 
resources to either True or False in the resource file (see Section 3.10.4). 

DebugSource.StartupShowSourceLineno: True 
Debuglnstruction.StartupShowInstLineno: True 

3.10.3 Modifying, Adding, Removing, and Resequencing Push Buttons 

The buttons on the push button view are associated with debugger commands. 
You can: 

• Change a button's label or associated command 

• Add a new button 

• Remove a button 

• Resequence a button 
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_ Note _ 

You cannot modify or remove the Stop button. 


To save these modifications for future debugger sessions, choose Save Options 
from the Options menu. 

Sections Section 3.10.3.1, Section 3.10.3.2, and Section 3.10.3.3 explain how 
to customize push buttons interactively through the DECwindows Motif 
interface. You can also customize push buttons by editing the resource file. 
Button definitions in the resource file begin with: 

DebugControl.Button 

(See Example 3-1.) 

3.10.3.1 Changing a Button’s Label or Associated Command 

To change a button’s label or associated command: 

1. Choose Customize Buttons... from the Options menu on the main window or 
the optional views window. The Customize Buttons dialog box is displayed 
(see Figure 3-23). 

2. Within the dialog box, click on the button you are modifying. This fills the 
Command and Label fields with the parameters for that button. The example 
in Figure 3-23 shows that the Step button was selected. 

3. To change the button icon, pull down the Icon menu within the dialog box and 
select one of the predefined icons. As Figure 3-23 shows, the Label field dims 
and is filled with the debugger’s internal name for the predefined icon. The 
icon itself appears in the dialog box’s push button display. 

To change the button label, verify that the Icon menu is set to None and enter 
a new label in the Label field. 

4. To change the command associated with the button, then enter the new 
command in the Command field. For online help about the commands, see 
Section 1.4.3. 

If the command is to operate on a name or language expression selected in 
a window, specify %S as the command parameter. For example, the following 
command displays the current value of the language expression that is 
currently selected: 

EVALUATE %s 

If the command is to operate on a debugger built-in symbol or any other name 
that has a a percent sign (%) as the first character, specify two percent signs. 
For example: 

EXAMINE %%NEXTL0C 

5. Click on Modify. The button’s label or associated command is changed within 
the dialog box push button display. 

6. Click on Apply. The button’s label or associated command is changed within 
the debugger’s push button view. 
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Figure 3-23 Changing the Step-Button Label to an Icon 



To save these modifications for future debugger sessions, choose Save Options 
from the Options menu. 

3.10.3.2 Adding a New Button and Associated Command 

To add a new button to the push button view and assign a debugger command to 
that button: 

1. Choose Customize Buttons... from the Options menu. The Customize Buttons 
dialog box is displayed (see Figure 3-24). 

2. Enter the debugger command for the new button in the Command field (see 
Section 3.10.3.1). Figure 3-24 shows that the command RUN CP:X was 
chosen. This command runs a program called X.EXE. 

3. Enter a label for that button in the Label field or choose a predefined icon 
from the Icon menu. Figure 3-24 shows that the Run-X label was chosen. 

4. Click on Add. The button is added to the dialog box push button display. 

5. Click on Apply. The button is added to the debugger’s push button view. 

To save these modifications for future debugger sessions, choose Save Options 
from the Options menu. 

3.10.3.3 Removing a Button 

To remove a button: 

1. Choose Customize Buttons... from the Options menu on the main or optional 
views window. The Customize Buttons dialog box is displayed. 

2. Within the dialog box, click on the button you are removing. This fills the 
Command and Label fields with the parameters for that button. 

3. Click on Remove. The button is removed from the dialog box push button 
display. 

4. Click on Apply. The button is removed from the debugger’s push button view. 

To save these modifications for future debugger sessions, choose Save Options 
from the Options menu. 
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Figure 3-24 Adding a Button for the EXAMINE/ASCIZ Command 



3.10.3.4 Resequencing a Button 

To resequence a button: 

1. Choose Customize Buttons... from the Options menu on the main or optional 
views window. The Customize Buttons dialog box is displayed. 

2. Within the dialog box, click on the button you are resequencing. This fills the 
Command and Label fields with the parameters for that button. 

3. Click on the left or right arrow to move the button one position to the left or 
right. Continue to click until the button has moved, one position at a time, to 
its final position. 

4. Click on Apply to transfer this position to the debugger’s push button view. 

To save these modifications for future debugger sessions, choose Save Options 
from the Options menu. 

3.10.4 Editing the Debugger Resource File 

The debugger is installed on your system with a default debugger resource 
file (DECW$SYSTEM_DEFAULTS:VMSDEBUG.DAT) that defines the default 
display configuration for the debugger. When you modify the display attributes as 
described in Section 3.10 and then save the modifications with the Save Options 
command in the Options menu, the debugger creates a local debugger resource 
file, DECW$USER_DEFAULTS:VMSDEBUG.DAT. You can edit this file to further 
modify the debugger display configuration. 

If you do not have a local debugger resource file, you can create one with 
the Restore Default Options item in the Options menu. Whenever you start 
the debugger, it creates the debugger display configuration as defined in 
the most recent version of the local debugger resource file if there is one, 
otherwise, the debugger uses the definitions in the system debugger resource 
file, DECW$SYSTEM_DEFAULTS:VMSDEBUG.DAT. 

You cannot edit the system resource file. You can modify the debugger display 
configuration only by following the procedures in Section 3.10.1, Section 3.10.2, 
and Section 3.10.3, or by editing and saving your local debugger resource file. 
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Example 3-1 contains a copy of the system default debugger resource file. Most 
entries are annotated within the file or are self-explanatory. Section 3.10.4.1, 
Section 3.10.4.2, Section 3.10.4.3, and Section 3.10.4.4 contain additional 
information about modifying certain key sequences. For complete information 
about specifying key sequences, see the translation table syntax in the X Toolkit 
Intrinsics documentation. 


_ Note _ 

The line in Example 3-1 that begins with DebugControl.ButtonList 
does not completely fit in this example. This line identifies the button 
definitions contained in the file. The full line in the file also contains 
the following button names: StepReturnButton, StepCallButton, 
ExamineButton, ExamineASCIZButton, ExamineASCICButton, 
EvalButton, MonitorButton 


Example 3-1 System Default Debugger Resource File (DECW$SYSTEM 
DEFAULTS:VMSDEBUG.DAT) 

! OpenVMS 64bit Debugger Resource File 

j 

DebugVersion: 7 

i 

! GEOMETRY RESOURCES: Automatically created/saved when a user executes 
! "SAVE OPTIONS" from the Options menu. 

I 

DebugSource.x: 11 

DebugSource.y: 30 

DebugSource.width: 620 
DebugSource.height: 700 

I 

DebugControl.x: 650 

DebugControl.y: 30 

DebugControl.width: 600 
DebugControl.height: 700 

j 

DebugEditor.x: 650 

DebugEditor.y: 30 

DebugEditor.width: 600 
DebugEditor.height: 700 

i 

Debuglnstruction.x: 11 
Debuglnstruction.y: 769 

Debuglnstruction.width: 620 

Debuglnstruction.height: 243 

j 

*DebugBrowser.x: 650 

*DebugBrowser.y: 30 

*DebugBrowser.width: 600 
*DebugBrowser.height: 350 
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Example 3-1 (Cont.) System Default Debugger Resource File (DECW$SYSTEM 
DEFAULTSrVMSDEBUG.DAT) 

! LINE NUMBER DISPLAY RESOURCES: 

! Create the line or address number display in views at startup? 

I 

DebugSource.StartupShowSourceLineno: True 
Debuglnstruction.StartupShowInstLineno: True 
Debuglnstruction.StartupShowInstAddrno: False 

i 

! WINDOW PANE RESOURCES: Relative size of panes in main window. 

! Main window height is derived from sum of panes. 

I 

DebugSource*SrcView.height: 460 

DebugSource*PushbuttonPanel.height: 36 
DebugSource*MessageOutputPanel.height: 145 

j 

DebugControl.BreakpointView.height: 175 
DebugControl.MonitorView.height: 150 
DebugControl.TaskView.height: 130 

DebugControl.RegisterView.height: 250 

j 

! The following resources determine which buttons to put in the button panel. 

! Buttons will show in the order they are listed here. 

! For each button there MUST be a set of associated resources. 

! EXAMPLE: 

! ButtonCommand - Associates a command with the button. 

! ButtonLegend - Button Label or pixmap name if pixmap flag is True. 

! ButtonPixmapFlag - If True uses ButtonLegend as predefined pixmap name. 

j 

DebugControl.ButtonList: \ GoButton, StepButton, StepInButton, ... 

i 

DebugControl.ButtonCommand.GoButton: go 
DebugControl.ButtonLegend.GoButton: go_pixmap 
DebugControl.ButtonPixmapFlag.GoButton: True 

j 

DebugControl.ButtonCommand.StepButton: step 
DebugControl.ButtonLegend.StepButton: STEP 
DebugControl.ButtonPixmapFlag.StepButton: False 

I 

DebugControl.ButtonCommand.StepInButton: step/in 
DebugControl.ButtonLegend.StepInButton: S/in 
DebugControl.ButtonPixmapFlag.StepInButton: False 

j 

DebugControl.ButtonCommand.StepReturnButton: step/return 
DebugControl.ButtonLegend.StepReturnButton: S/ret 
DebugControl.ButtonPixmapFlag.StepReturnButton: False 

i 

DebugControl.ButtonCommand.StepCallButton: step/call 
DebugControl.ButtonLegend.StepCallButton: S/call 
DebugControl.ButtonPixmapFlag.StepCallButton: False 

j 

DebugControl.ButtonCommand.ExamineButton: examine %s 
DebugControl.ButtonLegend.ExamineButton: EX 
DebugControl.ButtonPixmapFlag.ExamineButton: False 

i 

DebugControl.ButtonCommand.ExamineASCIZButton: examine/asciz %s 
DebugControl.ButtonLegend.ExamineASCIZButton: E/az 
DebugControl.ButtonPixmapFlag.ExamineASCIZButton: False 

i 

DebugControl.ButtonCommand.ExamineASCICButton: examine/ascic %s 
DebugControl.ButtonLegend.ExamineASCICButton: E/ac 


(continued on next page) 
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Example 3-1 (Cont.) System Default Debugger Resource File (DECW$SYSTEM 
DEFAULTS: VMSDEBUG.DAT) 

DebugControl.ButtonPixmapFlag.ExamineASCICButton: False 

i 

DebugControl.ButtonCommand.EvalButton: evaluate %s 
DebugControl.ButtonLegend.EvalButton: EVAL 
DebugControl.ButtonPixmapFlag.EvalButton: False 

j 

DebugControl.ButtonCommand.MonitorButton: monitor %s 
DebugControl.ButtonLegend.MonitorButton: MON 
DebugControl.ButtonPixmapFlag.MonitorButton: False 

j 

! THE FOLLOWING RESOURCES CAN ONLY BE CHANGED BY EDITING THIS FILE. 


! Be sure to trim any trailing white-spaces. 

j 

! FONT RESOURCES: 

j 

! If a font is specified for a view, and the font is available on the 
! system, it will be used for that view. 

j 

! For any views which do not explicitly specify a font, the font specified 
! by the resource "DebugDefault.Font" will be used if it is available on the 
! system. 

I 

! If no font resources are specified at all, the debugger will use the 
! systems own default font specification. 

j 

! The "DebugOptions.Font" applies to all optional views. We suggest that 

! you select a font with a point size no larger than 14 in the option views 

! in order to preserve label alignment. 

i 

! Using 132 column sources? Try this font: 

! -dec-terminal-medium-r-narrow--14-100-100-100-c-60-iso8859-l 

i 

! FORMAT: -*-FONTNAM-FACE-T-*—*-PTS-*-*-*-*-CHARSET 

j 

DebugDefault.Font: -*-C0URIER-B0LD-R-*—*-120-*-*-*-*-ISO8859-l 
DebugSource.Font: -*-COURIER-BOLD-R-*--*-120-*“*-*-*-ISO8859-l 

Debuglnstruction.Font: -*-C0URIER-B0LD-R-* —*-140-*-*-*-*-ISO8859-l 

DebugMessage.Font: -*-COURIER-BOLD-R-*--*-120-*-*-*-*-ISO8859-l 

DebugOptions.Font: -*-C0URIER-B0LD-R-*--*-120-*-*-*-*-ISO8859-l 

i 

! STARTUP STATE: 3=Iconified, 0=Visible 

i 

DebugSource.initialState: 0 
DebugControl.initialState: 0 
DebugEditor.initialState: 0 

Debuglnstruction.initialState: 0 

j 

! COLORS (Use any of the OSF Motif Named Colors) 

! Foreground = Text Color, Background = Window Color 

j 

! Source View Colors 

i 

DebugSource*src_txt.foreground: blue 
DebugSource*src_txt.background: white 

DebugSource*src_lineno_txtw.foreground: red 
DebugSource*src_lineno_txtw.background: white 
DebugSource*cnt_msg_txt.foreground: black 
DebugSource*cnt_msg_txt.background: white 


(continued on next page) 
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Example 3-1 (Cont.) System Default Debugger Resource File (DECW$SYSTEM 
DEFAULTS:VMSDEBUG.DAT) 

! Instruction View Colors 

i 

DebugInstruction*inst_txt.foreground: blue 
DebugInstruction*inst_txt.background: white 
DebugInstruction*inst_addrno_txtw.foreground: red 
DebugInstruction*inst_addrno_txtw.background: white 

j 

! Editor Colors 

j 

DebugEditor*edit_textw.foreground: black 
DebugEditor*edit_textw.background: white 

j 

! KEY SEQUENCES: 

| 

! Key sequence used to activate the dialog box for conditional and action 
! breakpoints. 

i 

DebugSource.ModifyBreakpointToggleSequence: Ctrl <BtnlDown>, Ctrl <BtnlUp> 

j 

! GENERAL KEYPAD FUNCTIONS: 

| 

!<Key>0xFFB0=KP0, <Key>OxFF91,<Key>OxFFBO=GOLD-KPO, 

!<Key>0xFF94,<Key>0xFFB0=BLUE-KP0, <Key>OxFFBl=KPl, 

!<Key>0xFF91,<Key>OxFFBl=GOLD-KPl, <Key>OxFFAC=KP, 

DebugSource.*XmText.translations:#override\n\ 

<Key>0xFFB0: EnterCmdOnCmdLine("step/line") \n\ 

<Key>OxFFBl: EnterCmdOnCmdLine("examine") \n\ 

<Key>OxFFAC: EnterCmdOnCmdLine("go") \n\ 

<Key>0xFF91,<Key>0xFFB0: EnterCmdOnCmdLine("step/into") \n\ 

<Key>0xFF94,<Key>0xFFB0: EnterCmdOnCmdLine("step/over") \n\ 

<Key>0xFF91,<Key>OxFFBl: EnterCmdOnCmdLine("examine A ") \n\ 

<Key>0xFFB5: EnterCmdOnCmdLine("show calls") \n\ 

<Key>0xFF91,<Key>0xFFB5: EnterCmdOnCmdLine("show calls 3") \n\ 

<Key>0xFF8D: activate()\n 

I 

! IDENTIFIER WORD SELECTION: (language-based delimiters) 

! NOTE: DO NOT use any double click combinitation for the following resource 
! otherwise normal text selection in the source window will not work. 

I 

DebugSource.IdentifierSelectionSequence: Ctrl<BtnlDown> 

i 

! EXIT CONFIRMATION: 

\ 

DebugDisplayExitConfirmDB: True 

I 

! COMMAND ECHO: 

i 

DebugEchoCommands: True 

I 

! TITLE FORMAT: Main window and optional view window. 

I 

! The following title format directives are supported: 

I 

! %t - The title of the debugger application. 

! %p - The name of the user program being debugged. 

! %f - The name of the current file displayed in the source window. 

I 

DebugControl.TitleFormat: %t - %p: %f 


(continued on next page) 
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Example 3-1 (Cont.) System Default Debugger Resource File (DECW$SYSTEM_ 
DEFAULTS:VMSDEBUG.DAT) 

! DRAG AND DROP MESSAGE SUPRESSION: 

j 

*.draglnitiatorProtocolStyle: DRAG_N0NE 
*.dragReceiverProtocolStyle: DRAG_N0NE 

3.10.4.1 Defining the Key Sequence to Display the Breakpoint Dialog Box 

By default, the key sequence for displaying the dialog box for conditional and 
action breakpoints is Ctrl/MBl (see Section 3.4.6 and Section 3.4.7). To define 
another key sequence, edit the current definition of the following resource in the 
resource file. For example: 

DebugSource.ModifyBreakpointToggleSequence: Ctrl<BtnlDown>(2) 

3.10.4.2 Defining the Key Sequence for Language-Sensitive Text Selection 

By default, the key sequence for language-sensitive text selection in the main 
window and instruction view is Ctrl/MBl (see Section 3.5.1). To define another 
key sequence, edit the current definition of the following resource in the resource 
file. For example: 

DebugSource.IdentifierSelectionSequence: Ctrl<BtnlDown> 

To avoid conflict with standard DECwindows Motif word selection, do not use a 
double-click combination, such as Ctrl<BtnlDown>(2). 

3.10.4.3 Defining the Font for Displayed Text 

To define another font for the text displayed in various debugger windows and 
views, edit the current definition of the following resources in the resource file. 
For example: 

DebugDefault.Font: -*-C0URIER-B0LD-R-*--*-120-*-*-*-*-ISO8859-l 


3.10.4.4 Defining the Key Bindings on the Keypad 

To bind a different command to a key that is already associated with a command, 
edit the current definition of the following resources in the resource file. For 
example: 

<Key>0xFFB0: EnterCmdOnCmdLine("step/line 3") \n\ 

To bind a command to a key that is not currently associated with a command, 
refer to the Keysym Encoding chapter of the X and Motif Quick Reference Guide 
for key designations. 

3.11 Debugging Detached Processes 

You cannot use the DECwindows Motif interface to the debugger to debug 
detached processes, such as print symbionts, which run without a command line 
interpreter (CLI). 

To debug a detached process that runs without a CLI, use the character-cell 
(screen mode) interface to the debugger (see Section 5.3.8.5). 
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_4 

Using the Heap Analyzer 


The Heap Analyzer, available on both Open VMS Alpha and OpenVMS VAX 
systems, is a feature of the debugger that provides a graphical representation of 
memory use in real time. By studying this representation, you can identify areas 
in your application where memory usage and performance can be improved. For 
example, you might notice allocations that are made too often, memory blocks 
that are too large, evidence of fragmentation, or memory leaks. 

After you locate an area of interest, you can request an enlarged, more detailed, 
or altered view. You can also request additional information on the size, contents, 
or address of the allocations shown. 

After you narrow your interest to an individual allocation, you can request 
traceback information. The analyzer allows you to correlate the traceback entry 
for an allocation with source code in your application program. By scrolling 
through the source code display, you can then identify problematic code and 
decide how to correct it. 

This chapter describes the following: 

• Starting a Heap Analyzer session (Section 4.1) 

• Working with the default display (Section 4.2) 

• Adjusting type determination and display (Section 4.3) 

• Exiting the Heap Analyzer (Section 4.4) 

• Sample session (Section 4.5) 

4.1 Starting a Heap Analyzer Session 

The following sections describe how to invoke the Heap Analyzer and run your 
application. 

4.1.1 Invoking the Heap Analyzer 

You can invoke the Heap Analyzer during a debugging session in one of the 
following ways: 

1. In the debugger main window, choose the Run Image or Rerun Same items 
from the File menu. When a dialog box appears, select the program you wish 
to execute and click the Heap Analyzer toggle button. 

2. At the debugger command entry prompt, enter the RUN/HEAP_ANALYZER 
or RERUN/HEAP_ANALYZER program-name command. 

3. At the DCL prompt ($) in a DECterm window outside the debugger, enter 
the following command and then execute your program: 

$ DEFINE/USER LIBRTL SYS$LIBRARY:LIBRTL INSTRUMENTED 
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(You can invoke the Heap Analyzer outside a debugging session by entering the 
DEFINE/USER command detailed above, and then the DCL command RUN 
/NODEBUG.) 

Note that the Heap Analyzer does not work on programs linked with the 
/NODEBUG qualifier on OpenVMS Alpha systems. On OpenVMS VAX systems, 
the Heap Analyzer does work on programs linked with the /NODEBUG qualifier, 
although the traceback information displayed will be minimal. 

After you successfully invoke the Heap Analyzer, the Heap Analyzer startup 
screen appears. 

4.1.2 Viewing Heap Analyzer Windows 

The Heap Analyzer contains a main window, six subsidiary windows, and a 
control panel (see Figure 4-1.) 

The Memory Map, the most important window, displays a representation of 
your application’s dynamic memory use. At startup, the Memory Map shows the 
images that comprise your application. As your application executes, you can 
see the relative location and size of individual memory blocks, images, program 
regions, memory zones, and dynamic strings as they are allocated and deallocated 
in memory space. 

The Message window displays information on your Heap Analyzer session. At 
startup, the Message window contains the message ’Heap Analyzer initialization 
complete. Press Start button to begin program.’ As your application executes, 
informational and error messages appear in this window. 

The Push Button Control Panel contains buttons that allow you to control the 
speed of the Memory Map display. At startup, you click on the Start button to 
begin executing your application. As your application executes, you can click 
on other buttons in the panel to pause, slow, or otherwise affect the continuous 
display. 

The Information window displays information on Memory Map segments. As 
your application executes, you can pause execution at any time to request specific 
information. 

The Source window displays the application source code associated with a 
segment in the Memory Map. 

The Do-not-use Type List allows you to adjust the Memory Map display by 
redetermining a segment’s type, or group name. 

The Views-and-Types Display allows you to adjust the Memory Map display by 
selectively viewing certain segment types. 

The Type Histogram displays summary and statistical information on segment 
types. 

As you use the Heap Analyzer, you may need to increase or decrease the size of 
the window in which you are working. To do this, pull the window pane sashes 
between windows or resize the screen as a whole. 
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Figure 4-1 Heap Analyzer Windows 



1. Memory Map Shows the graphical representation of memory, that 

is, the part of PO-space that is in use. Each allocation 
appears as a colored strip, or segment. 


2. Message window Displays Heap Analyzer informational and error 

messages and one-line segment descriptions. 

3. Information window Shows additional information on segments and 

segment types that appear in the Memory Map. 


4. Source window 

5. Do-not-use Type List 

6. Views-and-Types Display 


Shows application source code. 

Lists routines not used as segment types, the name 
that characterizes segments. 

Lists all segment types known to the Heap Analyzer 
and allows you to alter the segment display. 


7. Push Button Control Panel Provides Start/Step, Pause, Slow, and Sync buttons 

that allow you to control the speed of Memory Map 
display. 

8. Type Histogram Shows statistics on segment size and use. 
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4.1.3 Viewing Heap Analyzer Pull-Down Menus 

The Heap Analyzer provides five pull-down menus that are grouped over the 
Memory Map (see Figure 4-2). This figure is adjusted slightly so that all menu 
items can be seen. 


Figure 4-2 Heap Analyzer Pull-Down Menus 
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Reduce Scroll Region 
Display All Segments 
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On Window 
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1. File Menu 

2. Display Menu 

3. Zoom Menu 

4. Options Menu 

5. Help Menu 


Allows you to exit from the Heap Analyzer. 

Allows you to adjust the Memory Map display and to clear the 
Information window. 

Provides a closer or further view of the Memory Map. 

Allows you to indicate a search directory list or to adjust the Do-not- 
use Type List. 

Provides context-sensitive or task-oriented online help. 
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4.1.4 Viewing Heap Analyzer Context-Sensitive Menus 

Most operations in the Heap Analyzer, however, are accomplished through 
context-sensitive pop-up menus. Most Heap Analyzer windows contain a pop-up 
menu listing available tasks (see Figure 4-3). To access a window’s pop-up menu, 
position your mouse pointer in the window and click MB3. 


Figure 4-3 Heap Analyzer Context-Sensitive Pop-Up Menus 



Traceback of Allocation 
Display Segment 
Display Contents 
Display Address 
Display Type 
Go to Type 
Do Not Use Type 
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Display Type 
Go to Type 
Do Not Use Type 


e 


Go to Source 
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Use Type 
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Display Type 

fill 
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Show 

Expand 

Collapse 

Save 

Remove 




Go to Type 

Do Not Use Type 


Hide 



Reset 

Reset 

Reset 


1. Memory Map Pop-Up 


2. Information Window Pop-Up 

3. Do-not-use Type List Pop-Up 

4. Views-and-iypes Display Pop-Up 


5. Type Histogram Pop-Up 


Provides additional information on segments 
displayed in the Memory Map, allows you to 
jump to a segment’s type in the Views-and- 
Types Display, or adds a segment’s type to the 
Do-not-Use Type List. 

Allows you to jump from a line of traceback 
displayed in the Information window to the 
related source code in the Source window. 

Deletes a segment’s type from the Do-not-Use 
Type List. 

Left side: Provides additional information on 
segment types listed, highlights a segment type 
within the Views-and-Types Display, or adds a 
segment type to the Do-not-Use Type List. 

Right side: Allows you to adjust display 
characteristics for the segment type highlighted 
in the left side of the Views-and-Types Display. 

Provides additional information on segment types 
listed, highlights a segment type in the Type 
Histogram, or adds the segment type to the 
Do-not-Use Type List. 
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4.1.5 Setting a Source Directory 

If you are invoking the Heap Analyzer from a directory other than the one that 
stores your application source code, you can set a source directory for the Heap 
Analyzer as soon as the startup screen appears. 

To set a source directory: 

1. Choose the Set Source... menu item from the Options menu on the Heap 
Analyzer screen. 

The Set Source dialog box appears. 

2. Enter the directory specification for your source directory as you would for the 
OpenVMS Debugger SET SOURCE command. 

For more information on this command, see the debugger online help. 

3. Click on OK. 

The Heap Analyzer can now access your application. 

4.1.6 Starting Your Application 

If you invoked the Heap Analyzer from within a debugging session, start your 
application by performing the following steps: 

1. Click on the Start button in the Push Button Control Panel. 

The Message window displays an "application starting" message, and the 
Start button label changes to Step. The OpenVMS Debugger main window 
pops forward. 

2. Click on the Go button in the OpenVMS Debugger’s control panel, and iconize 
the OpenVMS Debugger window. 

Memory events associated with your application begin showing in the Memory 
Map. 

(If you invoked the Heap Analyzer outside a debugging session, start your 
application by performing only step 1 above.) 

After your application is running, the Memory Map (and other parts of the Heap 
Analyzer display) are continuously updated to reflect the state of your application. 

Unless you intervene (see Section 4.1.7), this updating continues until an 
occurrence causes memory events to stop. For example, your application might 
prompt for input, the debugger might prompt for input, or your application might 
finish execution. 

4.1.7 Controlling the Speed of Display 

To examine events in the Memory Map as your application is executing, you can 
use the Heap Analyzer’s push buttons to slow, pause, and otherwise affect the 
speed of the display. Figure 4-4 shows these push buttons on the Heap Analyzer 
window just after the Start button was pushed. 

The Slow and Pause push buttons allow you to slow or pause the display. 

The Step push button allows you to single-step through memory events. 

The Sync histogram (not shown) to the right of the Sync button indicates how far 
behind your application the Heap Analyzer is running. For performance reasons, 
the Heap Analyzer displays memory events a few seconds after their occurrence 
in your application. 
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Figure 4-4 Heap Analyzer Control Panel 



1. Start Button Click to start executing your application and enable the Memory Map 

display. Once you do so, the Start button changes to a Step button, 
which is initially dimmed (inaccessible). 

2. Step Button Click to single-step through memory events in the Memory Map 

display. This button is dimmed until you click on the Pause button. 


3. Pause Button 

4. Slow Button 

5. Sync Button 


Click to stop (or restart) execution of your application and the dynamic 
Memory Map display. 

Click to slow the dynamic Memory Map display. 

Click to force concurrent execution of your application program and 
display of memory events in the Memory Map. 


The Sync push button allows you to synchronize Heap Analyzer display and 
application execution, if this is important to you. Your application runs more 
slowly when you request synchronization. 
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Alpha 


On OpenVMS Alpha systems, anything that uses system service interception, 
like the debugger or the Heap Analyzer, is unable to intercept system service call 
images activated by shared linkage. The image activator, therefore, avoids shared 
linkage for images linked or run with /DEBUG, and instead activates private 
image copies. This affects performance of applications under Heap Analyzer 
control, as images activated by shared linkage run faster. ♦ 


4.2 Working with the Default Display 

The following sections describe how to use the Heap Analyzer when memory 
problems are clearly visible in the default Memory Map display. 

Visible problems include allocations that are larger than you expect, that repeat 
numerous times, that increment at each allocation, and that could occur in a 
more efficient way. 

In such cases, your Heap Analyzer session consists of the following steps: 

1. Examine the Memory Map display. 

2. Set display characteristics in the Memory Map (optional). 

3. Request additional information on individual segments (optional). 

4. Request traceback information on individual segments. 

5. Correlate traceback entries with source code routines. 

4.2.1 Memory Map Display 

Depending on the size of your application, you may wish to examine the Memory 
Map display as your application is running (by using the push buttons to slow, 
pause, or step through events) or after your application completes running (by 
using the Memory Map’s vertical scroll bar to scroll back through the display). 

You can identify segments whose size or location are not what you expect by 
remembering that a segment’s location in the Memory Map corresponds to 
its location in dynamic memory. Lower addresses in dynamic memory are 
represented in the upper left of the Memory Map display. Addresses increase to 
the right and wrap at each line of the display. 


4.2.2 Options for Memory Map Display 

As you examine the Memory Map, you may wish to select display options that 
allow you to see more clearly those parts of the display you are most interested 
in. 

The Display Menu allows you to control whether you see segment type names 
within the Memory Map display, whether the display automatically scrolls to 
show the most recent activity, and whether you can compress the display. 

The Zoom Menu allows you to control the degree of magnification with which you 
see segments in the Memory Map. Choosing the Far menu item, for example, 
shows an overview of memory. Choosing Extremely Close shows a more detailed 
view of memory. 

Figure 4-5 shows the display options that appear in the Display pull-down menu. 
The figure then lists all the display options available in the Memory Map. 
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Figure 4-5 Heap Analyzer Display Menu 



Heap Analyzer 


File Display Zoom Options 


M Text Visible 
K Auto Scroll 

Reduce Scroll Region 
Display All Segments 
Clear Information Window 


segments: 9: 00217300 




1005020 5 0 5 2050100 


O Pause □ Slow □ Sync 


Views 


1H show exp^ 
3how exp II 
HI show expj^j 


Blocks 


LIBRTL\LIB$VM\* 
LIBRTL\LIB$MALLOC 






Information window 


Source window 


1. Display Menu Text Visible: (Default.) Labels each segment in the Memory Map 

with a segment name, provided that the segment is large enough 
to carry a name label. 

Auto Scroll: (Default.) Automatically scrolls the Memory Map to 
the highest memory addresses (lower right) whenever the display 
is expanded. 

Reduce Scroll Region: When you request a limited or partial 
Memory Map display (see Section 4.3.3.2), compresses the display 
so that you can see as many segments as possible without scrolling 
to their location in the original display. 

Display All Segments: Displays segment definitions for all 
segments in the Memory Map. 

Clear Information Window: Clears text and messages from the 
Information window. 

2. Zoom Menu Options provide a closer or more distant view of the Memory Map. 
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4.2.3 


Options for Further Information 


As you examine the Memory Map display, you may find that you need more 
information on those segments that interest you. The Memory Map pop-up menu 
allows you to request segment, contents, address, and type definitions for an 
individual segment. 

A segment definition has the following form: 

cursor-address n:init-address + length = end-address name ( view ) 


cursor-address 

n 

init-address 

length 

end-address 

name 

view 


The address beneath your cursor when you click MB3. 

The number of your segment within the sequence of total segments. 
The initial address of your segment. 

The length (in bytes) of your segment. 

The last address of your segment. 

The segment type name of your segment. 

The view of your segment: block, image, region, or zone. (See 
Section 4.3.3.2 for more information on views.) 


For example, the following segment definition describes the 15th segment in your 
Memory Map display, which is a segment of type LIBRTL: 


0004ECA5 15: 00040000+0001CA00=0005CA00 LIBRTL (Image) 


A contents definition consists of a partial segment definition (a segment definition 
without a cursor-address) and an ASCII representation of the contents of segment 
addresses. For example: 


contents of: 38: 001C7000+000000C0=001C70C0 
LIBTRL\LIB$VM\LIB$GET VM (Block) 


[ASCII representation] 


An address definition takes the form of a statement describing user access to a 
stated address. For example: 


001C710B is read and write accessible by the user 

A type definition takes the form of a statement summarizing the total number of 
segments and total number of bytes devoted to a segment type. For example: 

LIBRTL\LIB$VM\LIB$GET_VM (Block) has 39 segments 
using 00002160 bytes 

Figure 4-6 shows the Memory Map context-sensitive pop-up menu. The figure 
then lists all the mouse and pop-up menu item choices available in the Memory 
Map. 


4-10 


Using the Heap Analyzer 
4.2 Working with the Default Display 


Figure 4-6 Heap Analyzer Memory Map Context-Sensitive Pop-Up Menu 



1. Memory Map Click MB1: Displays the segment definition in the Message window. 

2. Map Pop-Up Traceback of Allocation: Displays the traceback information associated 

with a segment in the Information window (see Section 4.2.4). 

Display Segment: Displays the segment definition in the Information 
window. 

Display Contents: Displays the segment definition and contents of each 
address in the Information window. 

Display Address: Displays the position (address) under your cursor and 
the type of user access in the Information window. 


Display Type: Displays the segment type definition in the Information 
window. 

Go to Type: Allows you to jump from a segment type listed in the Type 
Histogram to the same segment type listed in the Views-and-TVpes 
Display. 

Do Not Use Type: Adds a segment type to the Do-not-use Type List. 


4-11 

















































































Using the Heap Analyzer 

4.2 Working with the Default Display 


4.2.4 Requesting Traceback Information 

After you identify an individual segment of interest, choose the Traceback of 
Allocation menu item in the Memory Map pop-up menu. Traceback information 
can help you understand why your segment was created. Viewing traceback is 
also a preliminary step to displaying application code. 

Traceback information consists of a partial segment definition (a segment 
definition without a cursor address) and the list of elements on the callstack at 
the moment your segment was created. The element naming convention is image 
name\module name\routine name Mine number. For example: 

traceback: 8:000BA800+00065C00=00120400 DECC$SHR (Image) 

00066EDE DBG$HA_KERNEL 

00005864 CRL$MAIN_DB\CRL_LIBRARY\crl_initialize_libraries\%LINE 5592 

4.2.5 Correlating Traceback Information with Source Code 

When the traceback display appears, you identify the traceback entry most closely 
associated with the segment you are investigating. Most often, you can do this by 
comparing segment type names and traceback routine names. 

When you double click MB1 on this traceback entry, the source code associated 
with the entry appears (highlighted) in the Source window. You can then scroll 
through the source code display, identify problematic code, and decide how to 
correct it. 

If you cannot identify any problems in the displayed source code, return to the 
Information window and double click MB1 on the routine immediately above or 
below your previous choice. 

If you double click MB1 on a traceback entry, and ’Source Not Available’ messages 
appear in the Source window, you may have forgotten to set a source directory at 
the beginning of your Heap Analyzer session. See Section 4.1.5 for information on 
setting a search directory. 

Figure 4-7 shows the source code that appears when you double click MB1 on 
the traceback entry highlighted in the Information window. The figure then lists 
all the mouse and menu item choices available for the Source and Information 
windows. 
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Figure 4-7 Heap Analyzer Information and Source Windows 
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local_display_routine : REF .procedure 
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INITIALSdef_dis_ctl 


sea_message-handler ( local.displav.routiil 


crl.initializet.invocation-ref) 


return sca$_normal 
END: 


END 

ELUDOM 


! End of module 




1. Information Window Double click MB1: Allows you to jump from a line of 

traceback displayed in the Information window to the 
related source code in the Source window. 

2. Information Window Pop-Up Go to Source: Allows you to jump from a line of 

traceback displayed in the Information window to the 
related source code in the Source window. 


3. Display Menu 


Clear Information window: Clears text and messages 
from the Information window. 
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4.3 Adjusting Type Determination and Display 

The following sections describe the steps to perform when the memory events 
represented in the default Memory Map are not clear; that is, you cannot tell 
whether a problem exists or not. 

This circumstance can occur when the segment type names chosen by the Heap 
Analyzer are too broad to be useful for your application, or when the Memory 
Map is so full that you cannot easily see the segment of interest. 

In such cases, you can choose one or both of the following strategies: 

• Review the type summary in the Type Histogram (to see a summary, in total 
segments and total bytes, of each segment type’s use) 

• Adjust the type determination in the Memory Map (directing the Heap 
Analyzer to select type names that are more meaningful to you) 

• Adjust the type display in the Memory Map (directing the Heap Analyzer to 
suppress some types and highlight others) 

If, by adjusting the type determination or display, you then identify visible 
problems, you can resolve them in the same way you would if you were working 
with the default Memory Map display. (For more information, see Section 4.2.) 

4.3.1 Options for Further Information 

As you examine the Memory Map, you may wish to see a summary of Memory 
Map activity in the Type Histogram. The Type Histogram, which is two 
histograms back-to-back, shows the percentage of total segments and the 
percentage of total bytes devoted to each segment type in the Memory Map. 

To see these graphical representations in numeric form, click MB1 on the segment 
type of interest. 

To see the total number of segments or total number of bytes, check the top of 
each histogram. 

Figure 4-8 shows the types listed in the Type Histogram. (This window has been 
resized so all types appear.) The figure then lists all the mouse and menu item 
choices available in the Type Histogram. 
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Figure 4-8 Heap Analyzer Type Histogram 
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1. Type Histogram Click MB1: Displays the percentage of total segments 

and the percentage of total bytes represented by a 
segment. 

2. Type Histogram Pop-Up Display 'iype: Displays a type definition in the 

Information window. 

Go To Type: Allows you to jump from a segment type 
listed in the Type Histogram to the same segment type 
listed in the Views-and-Types Display. 

Do Not Use Type: Adds a segment type to the Do-not- 
use Type List. 
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4.3.2 Altering Type Determination 

As you examine the Memory Map, you may find that some segment type names 
are not meaningful to you. By adding these names to the Do-not-use Type List, 
you direct the Heap Analyzer to rename segments and, if necessary, regenerate 
the Memory Map display. 

By default, the analyzer assigns segment type names at the creation of a segment. 
In some cases, the analyzer assigns an element name (for example, LIBRTL). In 
most cases, however, the analyzer searches down the callstack to find a routine 
name that then serves as a segment type name. 

The analyzer chooses the first routine name on the callstack that is not prohibited 
by the Do-not-use Type List. If the first routine is prohibited, the analyzer 
examines the next routine down, and so on. 

This default behavior can cause the following Memory Map problems: 

• The same few type names appear repeatedly in the Memory Map display. 

This occurs when the first routines on the callstack are low-level memory 
management or utility routines. Since most of the allocation events in your 
application use these routines, you see unrelated allocations grouped together 
with the same type name. 

To prevent this problem, add any application-specific memory management 
or utility routine names to the Do-not-use Type List before you run your 
application. 

• The type names assigned provide a higher level of abstraction than you 
require. 

This can occur when the first routine on the callstack is less application- 
bound than your level of examination. If you need to see type names that 
reflect application functions, it is not helpful to see type names derived from 
intermediary memory management routines instead. 

This can also occur when the first routine on the callstack focuses on a part of 
your application you are not interested in examining. If you need to see type 
names that reflect subsystem functions (for example, initialize_death_star), 
it is not helpful to see only one type name for all subsystem functions (for 
example, initialize_star). 

To correct this problem, add the current type name to the Do-not-use Type 
List until the Memory Map display reflects the level of abstraction you desire. 

To add a segment type name to the Do-not-use Type List, you can select the 
Add to Do-not-use Type List pull-down menu item in the Options menu, or you 
can choose the Do Not Use Type pop-up menu item in the Memory Map, Type 
Histogram, or Views-and-Types Display. To delete a segment type from this list, 
choose the Use Type pop-up menu item in the Do-not-use Type List. 

To save the contents of a Do-not-use Type List, you can choose the Save Do-not- 
use Type List menu item in the Options menu. This saves the list for future Heap 
Analyzer sessions. The Restore Do-not-use Type List menu item removes recent 
additions to the list since the last time the list was saved. 

Figure 4-9 shows a LIBRTL\*\* entry in the Add to Do-not-use Type List dialog 
box you can choose from the Options menu. The figure then lists all the mouse 
and menu item choices available for the Do-not-Use Type List. 
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Figure 4-9 Heap Analyzer Do-Not-Use Type List 
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4.3.3 Altering the Views-and-Types Display 

As you examine the Memory Map, you may find that you need to adjust the 
type display to focus more clearly on your area of interest. The Views-and-Types 
Display allows you to specify changes to multiple or individual segments of the 
same type. 

The Views-and-Types Display is actually two windows separated by a window 
sash. You can expand the left window to show all the known types in your 
application. The right window contains the display options (color, show status, 
expand status, and save status). 

4.3.3.1 Selecting the Scope of Your Change 

The Heap Analyzer receives information about segments from four OpenVMS 
memory managers that perform allocations and deallocations in memory space. 
Each memory manager has a slightly different view, or overall picture, of dynamic 
memory. 

Each memory manager recognizes a different set of segment types. This means 
that, within the Heap Analyzer, where views from the memory managers are 
layered on each other, a single memory location can be associated with one or 
more segment types. 

The left window of the Views-and-Types Display contains a hierarchy that reflects 
this integration: 

• Views (integrates all four views) 

• Blocks (block view from LIB$VM memory manager) 

• Images (image view from SYS$IMAGE memory manager) 

• Regions (system services view from SYS$SERVICES memory manager) 

• Zones (zone view from LIB$VM_ZONE memory manager) 

To see the individual segment types recognized by each memory manager, expand 
the default display by double clicking MB1 on Blocks, Images, Regions, or Zones 
keywords. To collapse an individual listing, click MB3 on the keyword you 
previously selected. 

This hierarchy offers you the following choices in scope: 

• To affect all segment types in all views: 

Click MB1 on the Views keyword. 

• To affect all segment types in one view: 

Click MB1 on the Blocks, Images, Regions, or Zones keywords. 

• To affect individual segment types: 

Double click MB1 on the view of your choice, and click MB1 on one or more 
single segment types. 

Figure 4-10 shows the Block hierarchy item that is highlighted when you click 
MB1 to choose all blocks. The figure then lists all the mouse and menu item 
choices available in the hierarchy side of the Views-and-Types Display. 
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Figure 4-10 Heap Analyzer Views-and-Types Hierarchy 
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4.3.3.2 Choosing a Display Option 

The right window of the Views-and-Types Display shows the display options 
available, as follows: 

• Color 

To change the color of all segment types, all segment types in a particular 
view, or individual segment types, click MB3 on the color button in the 
display. When the vertical color strip appears, click MB1 on the color of your 
choice. Then, click the Apply button to apply your change. 

• Show (or hide) status 

To suppress (or restore) the display of all segment types, all segment types 
in a particular view, or individual segment types, toggle the Show button to 
the Hide (or Show) setting and click MB1. (Alternatively, you can choose the 
appropriate menu item from the Show pop-up menu.) Then, click the Apply 
button to apply your change. 

Use this option to clear the Memory Map of segments you are not examining. 
You can also use this option to find all segments of a particular type (by 
hiding every other segment). 

• Expand (or collapse) status 

To collapse (or expand) the display of segment types contained within all 
segment types, all segment types in a particular view, or individual segment 
types, toggle the Expand button to the Collapse (or Expand) setting and click 
MB1. (Alternatively, you can choose the appropriate menu item from the 
Expand pop-up menu.) Then, click the Apply button to apply your change. 

Use this option to clear the Memory Map of nested segments you are not 
examining. Depending on your application, Heap Analyzer performance may 
also improve. 

• Save (or remove) status 

To destroy (or save) information on all segment types, all segment types in 
a particular view, or individual segment types, toggle the Save button to the 
Remove (or Save) setting and click MB1. (Alternatively, you can choose the 
appropriate menu item from the Save pop-up menu.) Then, click the Apply 
button to apply your change. 

Use this option to clear the Memory Map completely, and then resume 
Memory Map display. See Section 4.5 to see how this can be valuable when 
you examine interactive commands. 

To cancel a choice, click the Reset button, or choose the Reset menu item from the 
Show, Expand, or Save pop-up menus. 

Figure 4—11 shows the Show pop-up menu that appears when you click MB3 on 
the options side of the Views-and-Types Display (the scope of your change, Blocks, 
has been previously highlighted). The figure then lists the mouse and menu item 
choices available in the options side of the Views-and-Types Display. 
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Figure 4-11 Heap Analyzer Views-and-Types Display Options 
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4.4 Exiting the Heap Analyzer 

To exit the Heap Analyzer, choose the Exit item from the File menu on the Heap 
Analyzer screen. 

4.5 Sample Session 

This section contains an example that shows how to combine information from 
Heap Analyzer windows and menus to locate a particular memory leak in your 
application. 

The example assumes that you have invoked the Heap Analyzer and run your 
application. As you scroll back through the Memory Map display, you focus your 
attention on segments that appear when your application calls for an interactive 
command. 

4.5.1 Isolating Display of Interactive Command 

You suspect that the leak occurs when you enter an interactive SHOW UNITS 
command, so your first step is to clear the Memory Map and reenter the 
command. 

To clear the Memory Map and reenter the command: 

1. Click on the Remove option for the Views item within the Views-and-Types 
Display. Then click on the Apply button. 

The Heap Analyzer clears all previous output from the Memory Map. 

2. Click on the Save option for the Views item. Then click on the Apply button. 
The Heap Analyzer will save all subsequent output to the Memory Map. 

3. In another DECterm window, at your application’s prompt, enter several 
SHOW UNITS commands. 

The Heap Analyzer shows a small series of segments that appear to be 
incrementing, but the scale is too small for you to be sure. 

4. Choose the Extremely Close menu item in the Zoom menu. 

The Heap Analyzer provides a closer view of the segments. 

The memory space allocated to each SCA__MEM_GET_VM segment is slightly 
larger with each SHOW UNITS command (see Figure 4—12). This growth in what 
should be a same-size allocation indicates a memory leak. 
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Figure 4-12 Incrementing Memory Allocation Indicates a Memory Leak 



4.5.2 Adjusting Type Determination 

The Heap Analyzer labels the segment type associated with your segments as 
SC A—MEM_GET_VM". This is a fairly low-level memory management routine 
that many segments might share. Your next step is to redefine the segment type 
to a more meaningful level of abstraction, perhaps one corresponding to the name 
of an application routine. 

To redefine the segment type: 

• Position your mouse pointer over one of the segments, and click MB3. 

The Heap Analyzer displays the Memory Map’s context-sensitive pop-up 
menu. 

• Choose the Do Not Use Type menu item from the pop-up menu. 

The segment type associated with your segment changes from M SCA_MEM_ 

GET_VM M to the more meaningful M crl_begin_unit_query M (see Figure 4-13). 
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Figure 4-13 Do Not Use Type Menu Item Redefines Segment Type 



4.5.3 Requesting Traceback Information 

After you determine the level of abstraction at which you want to view your 
segment, the next step is to examine the state of the call stack when the segment 
was allocated. Reviewing the traceback associated with a segment can reveal 
when and why it was created, and why a memory problem is occurring. 

To request traceback information: 

1. Position your mouse pointer over your segment, and click MB3. 

The Heap Analyzer displays the Memory Map’s context-sensitive pop-up 
menu. 

2. Choose the Traceback of Allocation menu item from the pop-up menu. 
Traceback information for your segment appears in the Information window. 
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4.5.4 Correlating Traceback with Source Code 

The traceback for your segment indicates that the crl_begin_unit_query routine 
sets up the environment for the SHOW UNITS command. To examine this event 
further, you can request to see the source code associated with it. 


To request source code, double-click MB1 on the traceback line that refers to 
crl_begin_unit_query. 

Source code appears in the Source window. The routine call that placed crl_ 
begin_unit_query on the callstack is highlighted (see Figure 4-14). 

Figure 4-14 Click on Traceback Entry Shows Associated Source Code 
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4.5.5 Locating an Allocation Error in Source Code 

After you connect a traceback entry to a routine in your application source code, 
you can enlarge the Source window and search for allocation errors in that source 
code location. 


For example, the highlighted line 5725 in Figure 4—15 makes an allocation 
to unit_query. This allocation is not deallocated before line 5740, where an 
additional allocation occurs. This coding error is the cause of your memory leak. 

Figure 4-15 Review of Source Code Shows Double Allocation 
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Part II 

Command Interface 


This part describes the debugger’s command interface. 

For information about the debugger’s DEC windows Motif interface, see Part I. 
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_5 

Introduction to the Debugger: Command 

Interface 


This chapter introduces the Open VMS Debugger’s command interface. The 
chapter provides the following information: 

• An overview of debugger features 

• Instructions to compile and link your program for debugging 

• Instructions to start and end a debugging session 

• A list of the debugger commands grouped by function 

For a tutorial introduction to the basic debugging tasks, see Chapter 6. 

5.1 Overview of the Debugger 

The debugger helps you locate run-time programming or logic errors, also known 
as bugs. You use the debugger with a program that has been compiled and linked 
successfully but does not run correctly. For example, the program might give 
incorrect output, go into an infinite loop, or terminate prematurely. 

You locate errors with the debugger by observing and manipulating your program 
interactively as it executes. By entering debugger commands at the terminal, you 
can: 

• Display your program’s source code, identifying where execution is currently 
paused 

• Browse through the source code to locate points of interest where you might 
test for certain conditions 

• Set breakpoints to suspend program execution at such points 

• Execute your program, including stepping one source line at a time and 
restarting from the beginning of the program 

• Trace the execution path of the program 

• Display the current value of a program variable 

Monitor changes in variables and other program entities during program 
execution 

• Change the value of a variable and, in some cases, test the modification 
without having to edit the source code, recompile, and relink 

Monitor exception conditions and language-specific events, and force events to 
occur 

These are the basic debugging techniques. After you are satisfied that you have 
found the error in the program, you can edit the source code and compile, link, 
and execute the corrected version. 
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As you use the debugger and its documentation, you will discover variations on 
the basic techniques. You can also customize the debugger for your own needs. 
The next section summarizes the debugger features. 


5.1.1 Functional Features 




Programming Language Support 

On VAX processors, you can use the debugger with programs written in the 
following VAX languages: 

Ada BASIC BLISS C 

C++ 1 COBOL DIBOL FORTRAN 

MACRO-32 Pascal PL/I RPGII 

SCAN ♦ 


Alpha 


1 Note that C++ functionality is minimal in this release. 


On Alpha processors, you can use the debugger with programs written in the 
following DEC languages: 


Ada 

BASIC 

BLISS 

c 

C ++ 1 

COBOL 

Fortran 

MACRO-32 2 

MACRO-64 

Pascal 

PL/I 

♦ 


1 Note that C++ functionality is minimal in this release. 

2 Note that MACRO-32 must be compiled with the AMACRO compiler. 

The debugger recognizes the syntax, data types, operators, expressions, scoping 
rules, and other constructs of a given language. You can change the debugging 
context from one language to another during a debugging session with the SET 
LANGUAGE command. 

Symbolic Debugging 

The OpenVMS Debugger is a symbolic debugger. You can refer to program 
locations by the symbols you used for them in your program—the names of 
variables, routines, labels, and so on. You do not need to specify memory 
addresses or machine registers when referring to program locations, although 
you can if you want. 

Support for All Data Types 

The debugger understands all compiler-generated data types, such as integer, 
floating-point, enumeration, record, array, and so on. It displays the values of 
program variables according to their declared type. 

Flexible Data Format 

The debugger permits a variety of data forms and types for entry and display. By 
default, the source language of the program determines the format used for the 
entry and display of data. You can also impose other formats. For example, by 
using a type or radix qualifier with the EXAMINE command, you can display the 
contents of a program location in ASCII, word-integer, or floating-point format. 

Starting or Resuming Program Execution 

You start or resume program execution with the GO or STEP commands. The 
GO command causes the program to execute until a breakpoint is reached, a 
watchpoint is modified, an exception is signaled, or the program terminates. The 
STEP command enables you to execute a specified number of lines or instructions, 
or up to the next instruction of a specified class. 
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Breakpoints 

By setting breakpoints with the SET BREAK command, you can suspend program 
execution at specified locations and check the current status of your program. 
Rather than specify a location, you can also suspend execution on certain classes 
of instructions or on every source line. Also you can suspend execution on certain 
kinds of events, such as exceptions and tasking (multithread) events. 

Tracepoints 

By setting tracepoints with the SET TRACE command, you can monitor the 
path of program execution through specified locations. When a tracepoint 
is triggered, the debugger reports that the tracepoint was reached and then 
continues execution. As with the SET BREAK command, you can also trace 
through classes of instructions and monitor events. 

Watchpoints 

By setting a watchpoint with the SET WATCH command, you can cause execution 
to stop whenever a particular variable or other memory location has been 
modified. When a watchpoint is triggered, the debugger suspends execution 
at that point and reports the old and new values of the variable. 

Manipulation of Variables and Program Locations 

With the EXAMINE command, you can determine the value of a variable or 
program location. The DEPOSIT command enables you to change that value. 

You can then continue execution to see the effect of the change without having to 
recompile, relink, and rerun the program. 

Evaluation of Expressions 

With the EVALUATE command, you can compute the value of a source-language 
expression or an address expression. You specify expressions and operators in the 
syntax of the language to which the debugger is currently set. 

Control Structures 

You can use logical control structures (FOR, IF, REPEAT, WHILE) in commands 
to control the execution of other commands. 

Shareable Image Debugging 

You can debug shareable images (images that are not directly executable). The 
SET IMAGE command enables you to access the symbols declared in a shareable 
image. 

Multiprocess Debugging 

You can debug multiprocess programs (programs that run in more than one 
process). The SHOW PROCESS and SET PROCESS commands enable you to 
display process information and control the execution of images in individual 
processes. 

Task Debugging 

You can debug tasking programs (also known as multithread programs). These 
programs use DECthreads or POSIX 1003.1b services, or use language-specific 
tasking services (for example, Ada tasking programs). The SHOW TASK and SET 
TASK commands enable you to display task information and control the execution 
of individual tasks. 


5-3 



Introduction to the Debugger: Command Interface 
5.1 Overview of the Debugger 

Vector Debugging 

On VAX processors, you can debug vectorized programs, that is, programs that 
use VAX vector instructions. You can control and monitor execution at the 
vector instruction level, examine and deposit vector instructions, manipulate the 
contents of vector registers, use a mask to display specific vector elements, and 
control synchronization between the scalar and vector processors. ♦ 

Terminal and Workstation Support 

The debugger supports all VT-series terminals and Micro VAX workstations. 

5.1.2 Convenience Features 

Online Help 

Online help is always available during a debugging session. Online help contains 
information about all debugger commands and selected topics. 

Source Code Display 

You can display source code for all supported languages during a debugging 
session. 

Screen Mode 

In screen mode, you can display and capture various kinds of information 
in scrollable windows that can be moved around the screen and resized. 
Automatically updated source, instruction, and register displays are available. 

You can selectively direct debugger input, output, and diagnostic messages to 
displays. You can also create DO displays that capture the output of specific 
command sequences. 

Running and Rerunning a Program 

With the RUN and RERUN commands, you can run a new program or rerun 
the same program from the current debugging session without having to first 
exit and restart the debugger. When you rerun a program, you can choose to 
either activate or deactivate any previously set breakpoints, tracepoints, and 
watchpoints. 

Keypad Mode 

When you start the debugger, several commonly used debugger command 
sequences are assigned by default to the keys of the numeric keypad (if you 
have a VT52, VT100, or LK201 keyboard). Thus, you can enter these commands 
with fewer keystrokes than if you were to type them at the keyboard. You can 
also create your own key definitions. 

Source Editing 

As you find errors during a debugging session, you can use the EDIT command to 
use any editor available on your system. You specify the editor you wish with the 
SET EDITOR command. If you use the DEC Language-Sensitive Editor (LSE), 
the editing cursor is automatically positioned within the source file whose code 
appears in the screen-mode source display. 

Command Procedures 

You can direct the debugger to execute a command procedure (a file of debugger 
commands) to re-create a debugging session, to continue a previous session, or 
to avoid typing the same debugger commands many times during a debugging 
session. You can pass parameters to command procedures. 
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Initialization Files 

You can create an initialization file containing commands to set your default 
debugging modes, screen display definitions, keypad key definitions, symbol 
definitions, and so on. When you start the debugger, those commands are 
executed automatically to tailor your debugging environment. 

Log Files 

You can record in a log file the commands you enter during a debugging session 
and the debugger’s responses to those commands. You can use log files to keep 
track of your debugging efforts, or you can use them as command procedures in 
subsequent debugging sessions. 

Symbol Definitions 

You can define your own symbols to represent lengthy commands, address 
expressions, or values in abbreviated form. 

5.2 Compiling and Linking Your Program for Debugging 

To bring a program under debugger control and take full advantage of symbolic 
debugging, you must first compile and link the program’s modules (compilation 
units) as explained in this section. 

The following example shows how to compile and link a C program, FORMS, that 
consists of two compilation units whose source code is in the files FORMS.C and 
INVENTORY.C. FORMS is the main program unit. 

On VAX processors, you explicitly identify linker options files in your LINK 
command: 


Alpha 


$ CC/DEBOG/NOOPTIMIZE INVENTORY,FORMS 
$ LINK/DEBUG FORMS,INVENTORY,0PTI0NS_FILE/0PTI0NS ♦ 

On Alpha processors, you do not identify linker options files: 

$ CC/DEBUG/NOOPTIMIZE INVENTORY,FORMS 
$ LINK/DEBUG FORMS,INVENTORY ♦ 

Note that the /DEBUG and /NOOPTIMIZE qualifiers are compiler command 
defaults for some languages. These qualifiers are used in the example for 
emphasis. (For information about compiling and linking that is specific to a 
particular language, see the documentation for that language.) 


5.2.1 Compiling 

In the previous examples, the /DEBUG qualifier on the compiler command (CC 
in this case) directs the compiler to write the symbol information associated with 
INVENTORY.C and FORMS.C into the object modules, INVENTORY.OBJ and 
FORMS.OBJ, respectively, in addition to the code and data for the program. This 
symbol information enables you to use the names of variables, routines, and other 
symbols declared in the program with debugger commands. If your program’s 
source code is in several files, you must compile each file whose symbols you 
want to reference with the /DEBUG qualifier. By specifying options with the 
/DEBUG qualifier, you can control the level of symbolic information provided (see 
Section 9.1.1). 

Some compilers optimize the object code to reduce the size of the program 
or to make it run faster. In such cases you should compile your program 
with the /NOOPTIMIZE command qualifier (or equivalent) when preparing 
for debugging. Otherwise, the contents of some program locations might be 
inconsistent with what you would expect from viewing the source code. For 
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example, some optimization techniques eliminate certain variables so that you 
no longer have access to them while debugging. (After the program has been 
debugged, you will probably want to recompile it without the /NOOPTIMIZE 
qualifier to take advantage of optimization.) Section 13.1 describes some of the 
effects of optimization. 

Note also another possible cause of unexpected behavior. Your program and parts 
of the debugger share the same address space. In some rare cases, this can cause 
the debugger to affect how your program executes. 

5.2.2 Linking 

In the previous examples, the /DEBUG qualifier on the LINK command directs 
the linker to include all symbol information that is contained in the object 
modules being linked (FORMS.OBJ and INVENTORY.OBJ, in this case) in the 
executable image. If your program has several object modules, you need to specify 
those modules in the LINK command (for most languages). See Section 9.1.3 for 
more details on how the LINK command controls symbol information. 

On VAX processors, the /OPTIONS qualifier indicates that OPTIONS_FILE is 
a linger options file. In the previous VAX example, the file specifies a run-time 
library to be linked with the program. ♦ 

5.2.3 Controlling Debugger Activation with the LINK and RUN Commands 

In addition to passing symbol information to the executable image, the 
LINK/DEBUG command causes the image activator to start the debugger if you 
execute the resulting image with the DCL RUN command. (This older, optional 
method of starting the debugger is explained in Section 5.3.8.1.) 

Even if you compile and link an image with the /DEBUG command qualifier, you 
can execute that image normally, without it being under debugger control. Use 
the /NODEBUG qualifier on the DCL RUN command. For example: 

$ RUN/NODEBDG FORMS 

This is convenient for checking your program after you think it is error free. 

Note that the data required by the debugger occupies space within the executable 
image. When you think your program is correct, you might want to link your 
program again without the /DEBUG qualifier. This creates an image with only 
traceback data in the debug symbol table which uses less disk space. 

Table 5-1 summarizes how to control debugger activation with the LINK and 
RUN command qualifiers. Note that the LINK command qualifiers /[NOJDEBUG 
and /[NOITRACEBACK affect not only debugger activation but also the maximum 
level of symbol information provided when debugging. 
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Table 5-1 Controlling Debugger Activation with the LINK and RUN Commands 

LINK Command 
Qualifier 

To Run Program without 
Debugger 

To Run Program with 
Debugger 

Maximum Symbol 
Information Available 1 

/DEBUG 

RUN/NODEBUG 

RUN 

Full 

None or 

/TRACEBACK or 
/NODEBUG 2 

RUN 

RUN/DEBUG 

Only traceback 3 

/NOTRACEBACK 

RUN 

RUN/DEBUG 4 

None 


1 The level of symbol information available while debugging is controlled both by the COMPILE command qualifier and 
the LINK command qualifier (see Section 9.1). 


2 LINK/TRACEBACK (or LINK/NODEBUG) is a LINK command default. 

3 TVaceback information includes compiler-generated line numbers and the names of routines and modules (compilation 
units). This symbol information is used by the traceback condition handler to identify the PC value (where execution is 
paused) and the active calls when a run-time error has occurred. The information is also used by the debugger SHOW 
CALLS command (see Section 6.3.3). 

4 The RUN/DEBUG command allows you to run the debugger, but if you entered the LINK/NOTRACEBACK command, 
you will be unable to do symbolic debugging. 


Alpha 


On Open VMS Alpha systems, anything that uses system service interception 
(SSI), like the debugger or the Heap Analyzer is unable to intercept system 
service call images activated by shared linkage. The image activator, therefore, 
avoids shared linkage for images linked or run with /DEBUG, and instead 
activates private image copies. This affects performance of user applications 
under debugger or Heap Analyzer control, as images activated by shared linkage 
run faster. ♦ 


5.3 Starting and Ending a Debugging Session 

This section explains how to: 

• Start the debugger and then bring a program under debugger control 

• Rerun the same program from the current debugging session 

• Run another program from the current debugging session 

• End a debugging session 

• Interrupt program execution and abort debugger commands 

• Interrupt a debugging session and then return to the debugging session 


The last part of this section describes additional ways to start the debugger for 
specific purposes. 

5.3.1 Starting the Debugger 

This section explains the usual way to start the debugger from DCL level ($) and 
bring your program under debugger control. Section 5.3.8 explains other, optional 
ways. 

Starting the debugger as explained here enables you to use the debugger’s 
RERUN and RUN features explained in Section 5.3.3 and Section 5.3.4, 
respectively. 
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To start the debugger and bring your program under debugger control: 

1. Verify that you have compiled and linked the program as explained in 
Section 5.2. 

2. Verify that the debugging configuration (default or multiprocess) 
is appropriate for the kind of program you are going to debug (see 
Section 5.3.8.3). For a program that runs in only one process (the typical 
case), use the default configuration. 

3. Enter the following command line: 

$ DEBUG/KEEP 

Debugger Banner and Version Number 

DBG> 

Upon startup, the debugger displays its banner and executes any user-defined 
initialization file (see Section 12.2). The DBG> prompt indicates that you can 
now enter debugger commands, as explained in Section 6.1. 

4. Bring your program under debugger control with the debugger RUN 
command, specifying the executable image of your program as the parameter. 
For example: 

DBG> RUN FORMS 

%DEBUG-I-INITIAL, language is C, module set to FORMS 
DBG> 

The message displayed indicates that this debugging session is initialized for a C 
program and that the name of the main program unit (the module containing the 
image transfer address) is FORMS. The initialization sets up language-dependent 
debugger parameters. These parameters control the way the debugger parses 
names and expressions, formats debugger output, and so on. See Section 8.1.8 
and Section 8.1.9 for more information about language-dependent parameters. 

Now program execution either pauses at the start of the main program unit or, 
with certain programs, at the start of some initialization code, before the main 
program. In the latter case, the debugger displays the following message: 

IDEBUG-I-NOTATMAIN, type GO to get to start of main program 

With some of these programs (for example, Ada programs), the first breakpoint 
enables you to debug the initialization code using full symbolic information. See 
Section 13.3 for more information. 

At this point, you can debug your program as explained in Chapter 6. 

RUN and RERUN Command Options for Programs That Require Arguments 

Some programs require arguments. This section explains how to execute 
such programs under debugger control with the debugger’s RUN and RERUN 
commands, and with the /ARGUMENTS and /COMMAND qualifiers. 

Following invocation of the debugger with the DCL command DEBUG/KEEP, you 
use the /ARGUMENTS qualifier with RUN to specify a list of arguments. Specify 
the program in one of two ways: Either specify the image name with RUN, or use 
the /COMMAND qualifier with RUN to specify a DCL foreign command. Note 
that the image name and the /COMMAND qualifier are mutually exclusive. 
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The different methods are shown in the following example of a debugger session. 
The source program is echoargs.c, a program that echoes the input arguments to 
the terminal: 

#include <stdio.h> 

main(int argc, char *argv[]) 

{ 

int i; 

for (i = 0; i < argc; i++) 
printf("%s\n M , argv[i]); 

} 

The program is compiled and linked as follows: 

$ cc/debug/noopt echoargs.c 
$ link/debug echoargs 

A DCL foreign command is defined as follows: 

$ ECHO == "$ sys$disk:[]echoargs.exe" 

The debugger is invoked. The debugger session in the example that follows shows 
three ways of passing arguments: 

1. RUN with /COMMAND and /ARGUMENTS 

The first section of the debugger session shows the use of the debugger 
RUN command with the /COMMAND and /ARGUMENTS qualifiers. 

The /COMMAND qualifier uses the DCL foreign command echo. The 
/ARGUMENTS qualifier specifies the actual arguments to the program, 
which are fa sol la mi. There is a GO to get to the start of the main program, 
and another GO to execute the program. The program correctly echoes the 
arguments to the screen: 

$ debug/keep 

Debugger Banner and Version Number 

DBG> run /command= n echo M /arguments="fa sol la mi" 

%DEBUG-I-INITIAL, language is C, module set to ECHOARGS 
%DEBUG-I-NOTATMAIN, type GO to get to start of main program 
DBG> go 

break at routine ECHOARGS\main 
265: { 

DBG> go 

_dsal:[jones.test]echoargs.exe; 2 

fa 

sol 

la 

mi 

%DEBUG-I-EXITSTATUS, is '%SYSTEM-S-NORMAL, normal successful completion' 

2. RERUN with /ARGUMENTS 

The second section of the same debugger session shows the use of the RERUN 
command with the /ARGUMENTS qualifier. It runs the same image again, 
with the new arguments fee fii foo fum. (If you omitted the /ARGUMENTS 
qualifier, the debugger would rerun the program with its previous arguments.) 
There is a GO to get to the start of the main program, and another GO to 
execute the program. The program correctly echoes the arguments to the 
screen: 
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DBG> rerun/arg="fee fii foo fum" 

%DEBUG-I-INITIAL, language is C, module set to ECHOARGS 
%DEBUG-I-NOTATMAIN, type GO to get to start of main program 
DBG> go 

break at routine ECHOARGS\main 
265: { 

DBG> go 

_dsal:[jones.test]echoargs.exe;2 

fee 

fii 

foo 

fum 

%DEBUG-I-EXITSTATUS, is '%SYSTEM-S-NORMAL, normal successful completion' 

3. RUN with /ARGUMENTS and image name 

The last section shows the use of the RUN command with an image name, 
echoargs , and the /ARGUMENTS qualifier. This command runs a new 
image, specified by the image name. This time, there is no DCL foreign 
command. The actual arguments to the program, a b c, are specified by 
the /ARGUMENTS qualifier. There is a GO to get to the start of the main 
program, and another GO to execute the program. The program correctly 
echoes the arguments to the screen: 

DBG> run/arg="a b c" echoargs 

%DEBUG-I-INITIAL, language is C, module set to ECHOARGS 
%DEBUG-I-NOTATMAIN, type GO to get to start of main program 
DBG> go 

break at routine ECHOARGS\main 
265: { 

DBG> go 

_dsal:[jones.test]echoargs.exe;2 
a 
b 
c 

%DEBUG-I-EXITSTATUS, is '%SYSTEM-S-NORMAL, normal successful completion' 
DBG> quit 

RUN Command Restrictions 

Note the following restrictions about the debugger RUN command: 

• You cannot use the RUN command to connect the debugger to a running 
program (see Section 5.3.8.2). 

• You cannot run a program under debugger control over a DECnet link. Both 
the image to be debugged and the debugger must reside on the same node. 

5.3.2 When Your Program Completes Execution 

When your program completes execution normally during a debugging session, 
the debugger issues the following message: 

%DEBUG-I-EXITSTATUS, is '%SYSTEM-S-NORMAL, normal successful completion' 

You then have the following options: 

• You can rerun your program from the same debugging session (see 
Section 5.3.3). 

• You can run another program from the same debugging session (see 
Section 5.3.4). 

• You can end the debugging session (see Section 5.3.5). 
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5.3.3 Rerunning the Same Program from the Current Debugging Session 

You can rerun the program currently under debugger control at any time during 
a debugging session, provided you originally started the debugger as explained in 
Section 5.3.1. Use the RERUN command. For example: 

DBG> RERUN 

%DEBUG-I-INITIAL, language is C, module set to FORMS 
DBG> 

The RERUN command terminates the image you were debugging and then brings 
a copy of that image under debugger control. Execution is paused at the start of 
the main program unit, as if you had used the RUN command (see Section 5.3.1). 

The RERUN command differs most notably from the RUN command in that 
RERUN lets you save the current state (activated or deactivated) of any 
breakpoints, tracepoints, and static watchpoints from the previous run of the 
program. The state of a particular nonstatic watchpoint might or might not be 
saved, depending on the scope of the variable being watched relative to the main 
program unit (where execution restarts). RERUN/SAVE is the default. If you do 
not want to save the current state, enter RERUN/NOSAVE instead of RERUN. 

The RERUN command uses the same version of the image that is currently under 
debugger control. To debug a different version of that program (or a different 
program) from the same debugging session, use the RUN command. To rerun 
a program with new arguments, use the /ARGUMENTS qualifier (see RUN and 
RERUN Command Options for Programs That Require Arguments). 

5.3.4 Running Another Program from the Current Debugging Session 

You can bring another program under debugger control at any time during a 
debugging session, provided you originally started the debugger as explained in 
Section 5.3.1. Use the debugger RUN command. For example: 

DBG> RUN TOTALS 

%DEBUG-I-INITIAL, language is FORTRAN, module set to TOTALS 
DBG> 

After the program has been brought under debugger control, execution is paused 
at the start of the main program unit. 

For more information about startup conditions and restrictions see Section 5.3.1. 

For information about all RUN command options, see the debugger RUN 
command description. 

5.3.5 Ending a Debugging Session 

To end a debugging session in an orderly manner and return to DCL level, enter 
EXIT or QUIT or press Ctrl/Z. For example: 

DBG> EXIT 
$ 

These commands start the debugger exit handlers to close log files, restore the 
screen and keypad states, and so on. 

The EXIT command and Ctrl/Z have the same effect. The QUIT command is like 
the EXIT command or Ctrl/Z, except that the EXIT command and Ctrl/Z also 
execute any exit handlers that are declared in your program; the QUIT command 
does not. 
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5.3.6 Interrupting Program Execution and Aborting Debugger Commands 

If your program goes into an infinite loop during a debugging session so that 
the debugger prompt does not reappear, press Ctrl/C. This interrupts program 
execution and returns you to the debugger prompt (pressing Ctrl/C does not end 
the debugging session). For example: 

DBG> GO 


[cwc] 

DBG> 

You can also press Ctrl/C to abort the execution of a debugger command. This is 
useful if, for example, the debugger is displaying a long stream of data. 

Pressing Ctrl/C when the program is not running or when the debugger is not 
performing an operation has no effect. 

If your program has a Ctrl/C AST (asynchronous system trap) service routine 
enabled, use the SET ABORT_KEY command to assign the debugger’s abort 
function to another Ctrl/key sequence. To identify the abort key that is currently 
defined, enter the SHOW ABORT_KEY command. 

Pressing Ctrl/Y from within a debugging session has the same effect as pressing 
Ctrl/Y during the execution of a program. Control is returned to the DCL 
command interpreter ($ prompt). 

5.3.7 Interrupting and Resuming a Debugging Session 

The debugger SPAWN and ATTACH commands enable you to interrupt a 
debugging session from the debugger prompt, enter DCL commands, and return 
to the debugger prompt. These commands function essentially like the DCL 
commands SPAWN and ATTACH: 

• Use the debugger SPAWN command to create a subprocess. 

• Use the debugger ATTACH command to attach to an existing process or 
subprocess. 

You can enter the SPAWN command with or without specifying a DCL command 
as a parameter. If you specify a DCL command, it is executed in a subprocess 
(if the DCL command invokes a utility, that utility is invoked in a subprocess). 
Control returns to the debugging session when the DCL command terminates 
(or when you exit the utility). The following example shows spawning the DCL 
command DIRECTORY: 

DBG> SPAWN DIR [JONES.PROJECT2]*.FOR 


%DEBUG-I-RETURNED, control returned to process J0NES_1 
DBG> 

The next example shows spawning the DCL command MAIL, which invokes the 
Mail utility: 
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DBG> SPAWN MAIL 
MAIL> READ/NEW 


MAIL> EXIT 

4DEBUG-I-RETURNED, control returned to process JONES 1 
DBG> 

If you enter the SPAWN command without specifying a parameter, a subprocess 
is created, and you can then enter DCL commands. Either logging out of the 
subprocess or attaching to the parent process (with the DCL ATTACH command) 
returns you to the debugging session. For example: 

DBG> SPAWN 
$. RON PR0G2 


$ ATTACH J0NES_1 

4DEBUG-I-RETURNED, control returned to process JONES 1 
DBG> 

If you plan to go back and forth several times between your debugging session 
and a spawned subprocess (which might be another debugging session), use the 
debugger ATTACH command to attach to that subprocess. Use the DCL ATTACH 
command to return to the parent process. Because you do not create a new 
subprocess every time you leave the debugger, you use system resources more 
efficiently. 

If you are running two debugging sessions simultaneously, you can define a new 
debugger prompt for one of the sessions with the SET PROMPT command. This 
helps you differentiate the sessions. 

5.3.8 Additional Options for Starting the Debugger 

In addition to the startup procedure described in Section 5.3.1, the following 
options are available for starting the debugger from DCL level: 

• Start the debugger by running the program to be debugged with the DCL 
RUN command (Section 5.3.8.1). 

• Interrupt a running program with Ctrl/Y and then start the debugger using 
the DCL DEBUG command (Section 5.3.8.2). 

• Establish a default or multiprocess debugging configuration to debug a 
program that runs in either one or several processes, respectively. 

Section 5.3.8.4 explains how to display the debugger’s command interface instead 
of the DECwindows Motif interface on a workstation running DECwindows Motif. 

5.3.8.1 Starting the Debugger by Running a Program 

You can start the debugger and also bring your program under debugger control 
in one step by entering the DCL command RUN program-image (assuming the 
image was linked with the /DEBUG qualifier). 

However, you cannot use the debugger RERUN or RUN features explained in 
Section 5.3.3 and Section 5.3.4, respectively. To rerun the same program or run 
another program under debugger control, you must first exit the debugger and 
start it again. 
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To start the debugger by running a program: 

1. Verify that you have compiled and linked the program as explained in 
Section 5.2 and that you have established the proper debugging configuration 
as explained in Section 5.3.8.3. 

2. Enter the DCL command RUN program-image to start the debugger. 

For example: 

$ RUN FORMS 

Debugger Banner and Version Number 

%DEBUG-I-INITIAL, language is C, module set to FORMS 
DBG> 

Upon startup, the debugger displays its banner, executes any user-defined 
initialization file, sets the language-dependent parameters to the source language 
of the main program, suspends execution at the start of the main program, and 
prompts for commands. 

For more information about startup conditions, see Section 5.2.3 and 
Section 5.3.1. 

S.3.8.2 Starting the Debugger After Interrupting a Running Program 

You can bring a program that is executing freely under debugger control. This is 
useful if you suspect that the program might be in an infinite loop or if you see 
erroneous output. 

To bring your program under debugger control: 

1. Verify that you have compiled and linked the program as explained in 
Section 5.2 and that you have established the proper debugging configuration 
as explained in Section 5.3.8.3. 

2. Enter the DCL command RUN/NODEBUG program-image to execute the 
program without debugger control. 

3. Press Ctrl/Y to interrupt the executing program. Control passes to the DCL 
command interpreter. 

4. Enter the DCL command DEBUG to start the debugger. 

For example: 

$ RUN/NODEBOG FORMS 


[CWYl 

Interrupt 
$ DEBUG 

Debugger Banner and Version Number 

%DEBUG-I-INITIAL, language is C, module set to FORMS 
DBG> 

Upon startup, the debugger displays its banner, executes any user-defined 
initialization file, sets the language-dependent parameters to the source language 
of the module where execution was interrupted, and prompts for commands. 


5-14 


Introduction to the Debugger: Command Interface 
5.3 Starting and Ending a Debugging Session 

Usually you will not know where execution was interrupted. Enter the SHOW 
CALLS command to determine where execution is paused and the sequence 
of routine calls on the call stack (the SHOW CALLS command is described in 
Section 6.3.3). 

When you start the debugger in this manner, you cannot then use the 
debugger RERUN or RUN features explained in Section 5.3.3 and Section 5.3.4, 
respectively. To rerun the same program or run another program under debugger 
control, you must first exit the debugger and start it ag ain . 

For more information about startup conditions, see Section 5.2.3 and 
Section 5.3.1. 

5.3.8.3 Establishing the Debugging Configuration 

You can start the debugger in either the default configuration or the 
multiprocess configuration to debug programs that run in either one or several 
processes, respectively. The configuration depends on the current definition of the 
logical name DBG$PROCESS. Before starting the debugger, enter the DCL 
command SHOW LOGICAL DBG$PROCESS to determine the definition of 
DBG$PROCESS: 

• If you are debugging a program that runs in only one process, 
DBG$PROCESS should be either undefined, as in the following example, 
or should have the value DEFAULT: 

$ SHOW LOGICAL DBG$PROCESS 

%SH0W-S-N0TRAN, no translation for logical name DBG$PROCESS 

By default, DBG$PROCESS is undefined, and this is appropriate for 
debugging a program that runs in only one process (the typical case). 

• If you are debugging a program that runs in more than one process, 
DBG$PROCESS should have the value MULTIPROCESS. 

• If DBG$PROCESS has the value MULTIPROCESS, and you want to debug a 
program that runs in only one process, enter the following command: 

$ DEFINE DBG$PROCESS DEFAULT 

For more information about multiprocess debugging, see Chapter 14. 

5.3.8.4 Displaying the Debugger’s Command Interface on a Workstation Running 
DECwindows Motif 

If you are at a workstation running DECwindows Motif, by default the debugger 
starts up in the DECwindows Motif interface, which is displayed on the 
workstation specified by the DECwindows Motif application-wide logical name 
DECW$DISPLAY. 

The logical name DBG$DECW$DISPLAY enables you to override the default to 
display the debugger’s command interface in a DECterm window, along with any 
program input/output (I/O). 

To display the debugger’s command interface in a DECterm window: 

1. Enter the following definition in the DECterm window from which you plan 
to start the debugger: 

$ DEFINE/JOB DBG$DECW$DISPLAY " " 

You can specify one or more space characters between the quotation marks. It 
is recommended that you use a job definition for the logical name. If you use 
a process definition, it must not have the CONFINE attribute. 
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2. Start the debugger in the usual way from that DECterm window (see 
Section 5.3.1). The debugger’s command interface is displayed in the same 
window. 

For example: 

$ DEFINE/JOB DBG$DECW$DISPLAY " " 

$ DEBUG/KEEP 

Debugger Banner and Version Number 

DBG> 

You can now bring your program under debugger control as explained 
in Section 5.3.1. For more information about the logical names 
DBG$DECW$DISPLAY and DECW$DISPLAY, see Section 2.7.3. 

5.3.8.5 Debugging Detached Processes that Run with No CLI 

The design and implementation of the debugger’s DECwindows Motif interface 
requires that the process being debugged have a command line interpreter (CLI). 
To debug a detached process (such as a print symbiont) that does not have a CLI, 
you must use the character-cell (screen mode) interface to the debugger. 

To do so, direct DBG$INPUT, DBG$OUTPUT and DBG$ERROR to a terminal 
port that is not logged in. This allows the image to be debugged with the 
standard character-cell interface on that terminal. 

For example: 

$ DEFINE/TABLE=GROUP DBG$INPUT TTA3: 

$ DEFINE/TABLE=GROUP DBG$OUTPUT TTA3: 

$ DEFINE/TABLE=GROUP DBG$ERR0R TTA3: 

$ START/QUEUE SYS$PRINT /PR0CESS0R=dev:[dir]test_program 
[Debugger starts up on logged-out terminal TTA3:] 

5.4 Debugger Command Summary 

The following sections list all the debugger commands and any related DCL 
commands in functional groupings, along with brief descriptions. During a 
debugging session, you can get online help on all debugger commands and their 
qualifiers by typing HELP at the debugger prompt (see Section 6.1). 

5.4.1 Starting and Ending a Debugging Session 

The following commands are used to start the debugger, bring a program under 
debugger control, and interrupt and end a debugging session. Except where the 
DCL RUN and DEBUG commands are indicated specifically, all commands are 
debugger commands. 
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DEBUG/KEEP 

(DCL DEBUG command) 

RUN SYS$SHARE:DEBUGSHR.EXE 

RUN program-image 

RERUN 


Starts the debugger. 

Starts the debugger. 

Brings a program under debugger control. 

Reruns the program currently under debugger 
control. 


RUN program-image 
(DCL RUN command) 


EXIT, Ctrl/Z 

QUIT 

Ctrl/C 

(SET,SHOW) ABORT_KEY 

Ctrl/Y-DEBUG 
(DCL DEBUG command) 

ATTACH 

SPAWN 


If the specified image was linked using LINK 
/DEBUG, starts the debugger and also brings 
the image under debugger control. When 
you start the debugger in this manner, you 
cannot then use the debugger RUN or RERUN 
commands. You can use the /[NO]DEBUG 
qualifiers with the RUN command to control 
whether the debugger is started when the 
program is executed. 

Ends a debugging session, executing all exit 
handlers. 

Ends a debugging session without executing 
any exit handlers declared in the program. 

Aborts program execution or a debugger 
command without interrupting the debugging 
session. 

(Assigns, identifies) the default Ctrl/C abort 
function to another Ctrl/key sequence, 
identifies the Ctrl/key sequence currently 
defined for the abort function. 

Interrupts a program that is running without 
debugger control and starts the debugger. 

Passes control of your terminal from the 
current process to another process. 

Creates a subprocess, which enables you to 
execute DCL commands without ending a 
debugging session or losing your debugging 
context. 


5.4.2 


Controlling and Monitoring Program 

The following commands are used to 

GO 

STEP 

(SET,SHOW) STEP 

(SET,SHOW,CANCEL) BREAK 
(ACTIVATE,DEACTIVATE) BREAK 

(SET,SHOW,CANCEL) TRACE 
(ACTIVATE,DEACTIVATE) TRACE 

(SET,SHOW,CANCEL) WATCH 
(ACTIVATE,DEACTIVATE) WATCH 


Execution 

control and monitor program execution: 

Starts or resumes program execution. 

Executes the program up to the next line, 
instruction, or specified instruction. 

(Establishes, displays) the default qualifiers 
for the STEP command. 

(Sets, displays, cancels) breakpoints. 

(Activates, deactivates) previously set 
breakpoints. 

(Sets, displays, cancels) tracepoints. 

(Activates, deactivates) previously set 
tracepoints. 

(Sets, displays, cancels) watchpoints. 

(Activates, deactivates) previously set 
watchpoints. 
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SHOW CALLS 
SHOW STACK 

CALL 

5.4.3 Examining and Manipulating Data 

The following commands are used 
EXAMINE 

SET MODE [NO]OPERANDS 

DEPOSIT 

EVALUATE 

MONITOR 


Identifies the currently active routine calls. 

Gives additional information about the 
currently active routine calls. 

Calls a routine. 


to examine and manipulate data: 

Displays the value of a variable or the 
contents of a program location. 

Controls whether the address and contents of 
the instruction operands are displayed when 
you examine an instruction. 

Changes the value of a variable or the 
contents of a program location. 

Evaluates a language or address expression. 

(Applies only to the debugger’s DECwindows 
Motif interface.) Displays the current value 
of a variable or language expression in the 
Monitor View of the DECwindows Motif 
interface. 


5.4.4 Controlling Type Selection and Radix 

The following commands are used to control type selection and radix: 


(SET,SHOW,CANCEL) RADIX 
(SET,SHOW,CANCEL) TYPE 

SET MODE [NO]G_FLOAT 


(Establishes, displays, restores) the radix for 
data entry and display. 

(Establishes, displays, restores) the type for 
program locations that are not associated with 
a compiler-generated type. 

Controls whether double-precision floating¬ 
point constants are interpreted as G_FLOAT 
or D_FLOAT. 


5.4.5 Controlling Symbol Searches and Symbolization 

The following commands are used to control symbol searches and symbolization: 

Displays symbols in your program. 

Sets a module by loading its symbol 
information into the debugger’s symbol table, 
identifies, cancels a set module. 


SHOW SYMBOL 

(SET,SHOW,CANCEL) MODULE 

(SET,SHOW,CANCEL) IMAGE 

SET MODE [NO]DYNAMIC 

(SET,SHOW,CANCEL) SCOPE 


Sets a shareable image by loading data 
structures into the debugger’s symbol table, 
identifies, cancels a set image. 

Controls whether or not modules and 
shareable images are set automatically when 
the debugger interrupts execution. 

(Establishes, displays, restores) the scope for 
symbol searches. 
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SYMBOLIZE 

SET MODE [NOJLINE 

SET MODE [NOJSYMBOLIC 

5.4.6 Displaying Source Code 

The following commands are 


Converts a memory address to a symbolic 
address expression. 

Controls whether or not program locations 
are displayed in terms of line numbers or 
routine-name + byte offset. 

Controls whether or not program locations are 
displayed symbolically or in terms of numeric 
addresses. 


used to control the display of source code: 


TYPE 

EXAMINE/SOURCE 

SEARCH 

(SET,SHOW) SEARCH 
SET STEP [NOISOURCE 

(SET,SHOW) MARGINS 
(SET,SHOW,CANCEL) SOURCE 

5.4.7 Using Screen Mode 

The following commands 

SET MODE [NOISCREEN 
DISPLAY 
SCROLL 
EXPAND 
MOVE 

(SHOW,CANCEL) DISPLAY 
(SET,SHOW,CANCEL) WINDOW 

SELECT 
SHOW SELECT 

SAVE 

EXTRACT 


Displays lines of source code. 

Displays the source code at the location 
specified by the address expression. 

Searches the source code for the specified 
string. 

(Establishes, displays) the default qualifiers 
for the SEARCH command. 

Enables/disables the display of source code 
after a STEP command has been executed or 
at a breakpoint, tracepoint, or watchpoint. 

(Establishes, displays) the left and right 
margin settings for displaying source code. 

(Creates, displays, cancels) a source directory 
search list. 


screen displays: 

Enables/disables screen mode. 

Creates or modifies a display. 

Scrolls a display. 

Expands or contracts a display. 

Moves a display across the screen. 

(Identifies, deletes) a display. 

(Creates, identifies, deletes) a window 
definition. 

Selects a display for a display attribute. 

Identifies the displays selected for each of the 
display attributes. 

Saves the current contents of a display into 
another display. 

Saves a display or the current screen state 
into a file. 


are used to control screen mode and 
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(SET,SHOW) TERMINAL 

SET MODE [NO]SCROLL 
Ctrl/W 

DISPLAY/REFRESH 

5.4.8 Editing Source Code 

The following commands are used 
session: 

EDIT 

(SET,SHOW) EDITOR 


(Establishes, displays) the terminal screen 
height and width that the debugger uses when 
it formats displays and other output. 

Controls whether an output display is updated 
line by line or once per command. 

Refreshes the screen. 


to control source editing from a debugging 

Starts an editor during a debugging session. 

(Establishes, identifies) the editor started by 
the EDIT command. 


5.4.9 Defining Symbols 

The following commands are used to define and delete symbols for addresses, 
commands, or values: 


DEFINE 


Defines a symbol as an address, command, or 
value. 


DELETE Deletes symbol definitions. 

(SET,SHOW) DEFINE (Establishes, displays) the default qualifier for 

the DEFINE command. 

SHOW SYMBOL/DEFINED Identifies symbols that have been defined with 

the DEFINE command. 


5.4.10 Using Keypad Mode 

The following commands are used to control keypad mode and key definitions: 


SET MODE [NOIKEYPAD 

DEFINE/KEY 

DELETE/KEY 

SET KEY 

SHOW KEY 


Enables/disables keypad mode. 
Creates key definitions. 

Deletes key definitions. 

Establishes the key definition state. 
Displays key definitions. 


5.4.11 Using Command Procedures, Log Files, and Initialization Files 

The following commands are used with command procedures and log files: 


@ (execute procedure) 
(SET,SHOW) ATSIGN 

DECLARE 

(SET,SHOW) LOG 
SET OUTPUT [NO]LOG 


Executes a command procedure. 

(Establishes, displays) the default file 
specification that the debugger uses to search 
for command procedures. 

Defines parameters to be passed to command 
procedures. 

(Specifies, identifies) the debugger log file. 

Controls whether or not a debugging session 
is logged. 
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SET OUTPUT [NO]SCREEN_LOG Controls whether or not, in screen mode, the 

screen contents are logged as the screen is 
updated. 

SET OUTPUT [NO]VERIFY Controls whether or not debugger commands 

are displayed as a command procedure is 
executed. 

SHOW OUTPUT Identifies the current output options 

established by the SET OUTPUT command. 

5.4.12 Using Control Structures 

The following commands are used to establish conditional and looping structures 
for debugger commands: 

Executes a list of commands while 
incrementing a variable. 

Executes a list of commands conditionally. 

Executes a list of commands a specified 
number of times. 

Executes a list of commands while a condition 
is true. 

Exits an enclosing WHILE, REPEAT, or FOR 
loop. 

5.4.13 Debugging Multiprocess Programs 

The following commands are used to debug multiprocess programs. Note that 
these commands are specific to multiprocess programs. Many of the commands 
listed under other categories have qualifiers or parameters that are specific 
to multiprocess programs (for example, SET BREAK/ACTIVATING, EXIT 
process-spec , DISPLAY/PROCESS=). 

Brings a process under debugger control. 

Assigns a symbolic name to a list of process 
specifications. 

Executes commands in the context of one or 
more processes. 

Controls whether execution is interrupted in 
other processes when it is paused in some 
process. 

Modifies the multiprocess debugging 
environment, displays process information. 


CONNECT 

DEFINE/PROCESS.GROUP 

DO 

SET MODE [NO]INTERRUPT 

(SET,SHOW) PROCESS 


FOR 

IF 

REPEAT 

WHILE 

EXITLOOP 


used for miscellaneous purposes: 


5.4.14 Additional Commands 

The following commands are 
HELP 

(DISABLE,ENABLE,SHOW) AST 
(SET,SHOW) EVENT_FACILITY 
(SET,SHOW) LANGUAGE 


Displays online help on debugger commands 
and selected topics. 

(Disables, enables) the delivery of ASTs in 
the program, identifies whether delivery is 
enabled or disabled. 

(Establishes, identifies) the current run-time 
facility for Ada, DECthreads, and SCAN 
events. 

(Establishes, identifies) the current language. 
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SET MODE [NO]SEPARATE 

SET OUTPUT [NO]TERMINAL 

SET PROMPT 
(SET,SHOW) TASK 

t(SET,SHOW) VECTOR_MODE 

SHOW EXIT_HANDLERS 
SHOW MODE 

SHOW OUTPUT 

tSYNCHRONIZE VECTOR_MODE 

tVAX specific 


Controls whether the debugger, when used 
on a workstation running VWS, creates a 
separate window for debugger input and 
output. 

Controls whether debugger output, except 
for diagnostic messages, is displayed or 
suppressed. 

Specifies the debugger prompt. 

Modifies the tasking environment, displays 
task information. 

Enables or disables a debugger vector mode 
option, identifies the current vector mode 
option (for vectorized programs). 

Identifies the exit handlers declared in the 
program. 

Identifies the current debugger modes 
established by the SET MODE command 
(for example, screen mode, step mode). 

Identifies the current output options 
established by the SET OUTPUT command. 

Forces immediate synchronization between 
the scalar and vector processors (for vectorized 
programs). 
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Command Interface 


This chapter gives a tutorial introduction to the debugger’s command interface. 

The way you use the debugger depends on several factors: the kind of program 
you are working on, the kinds of errors you are looking for, and your own 
personal style and experience with the debugger. This chapter explains the 
following basic tasks that apply to most situations: 

• Entering debugger commands and getting online help 

• Viewing your source code with the TYPE command and in screen mode 

• Controlling program execution with the GO, STEP, and SET BREAK 
commands, and monitoring execution with the SHOW CALLS, SET TRACE, 
and SET WATCH commands 

• Examining and manipulating data with the EXAMINE, DEPOSIT, and 
EVALUATE commands 

• Controlling symbol references with path names and the SET MODULE and 
SET SCOPE commands 

Several examples are language specific. However, the general concepts are 
readily adaptable to all supported languages. 

The sample debugging session in Section 6.6 shows how to use some of this 
information to locate an error and correct it. 

For information about starting and ending a debugging session, see Section 5.3. 

6.1 Entering Debugger Commands and Accessing Online Help 

After you start the debugger as explained in Section 5.3, you can enter debugger 
commands whenever the debugger prompt (DBG>) is displayed. To enter a 
command, type it at the keyboard and press Return. For example, the following 
command sets a watchpoint on the variable COUNT: 

DBG> SET WATCH COUNT 

Detailed reference information about debugger commands is available through 
the debugger’s online help: 

• To list the help topics, type HELP at the prompt. 

• For an explanation of the help system, type HELP HELP. 

• For complete rules on entering commands, type HELP Command_Format. 

• To display help on a particular command, type HELP command. For example, 
to display HELP on the SET WATCH command, type HELP SET WATCH. 
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• To list commands grouped by function, type HELP Command_Summary. 

Online help is also available on the following topics: 

New_Features 

Release_Notes 

Address_Expressions 

Built_in_Symbols 

Debugging_Configurations (default and multiprocess) 

DECwindows_Interface 

Keypad_Definitions 

Language_Support 

Logical_Names 

Messages (diagnostic messages) 

Path_Names (to qualify symbolic names) 

Screen_Mode 

SS$_DEBUG condition (to start debugger from program) 

System_Management 

VWS_Workstations 

To display help about any of these topics, type HELP topic. For example, to 
display information about diagnostic messages, type HELP Messages. 

When you start the debugger, a few commonly used command sequences are 
automatically assigned to the keys on the numeric keypad (to the right of the 
main keyboard). Thus, you can perform certain functions either by entering a 
command or by pressing a keypad key. 

The predefined key functions are identified in Figure 6-1. 

Most keypad keys have three predefined functions—DEFAULT, GOLD, and 
BLUE. 

• To enter a key’s DEFAULT function, press the key. 

• To enter its GOLD function, first press and release the PF1 (GOLD) key, and 
then press the key. 

• To enter its BLUE function, first press and release the PF4 (BLUE) key, and 
then press the key. 

In Figure 6-1, the DEFAULT, GOLD, and BLUE functions are listed within each 
key’s outline, from top to bottom, respectively. For example: 

• Pressing KPO (keypad key 0) enters the STEP command. 

• Pressing PF1 KPO enters the STEP/INTO command. 

• Pressing PF4 KPO enters the STEP/OVER command. 

Normally, keys KP2, KP4, KP6, and KP8 scroll screen displays down, left, 
right, or up, respectively. By putting the keypad in the MOVE, EXPAND, or 
CONTRACT state, indicated in Figure 6-1, you can also use these keys to 
move, expand, or contract displays in four directions. Enter the command 
HELP Keypad_Definitions to display the keypad key definitions. 

You can redefine keypad key functions with the DEFINE/KEY command. 
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Figure 6-1 Keypad Key Functions Predefined by the Debugger—Command Interface 
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6.2 Displaying Source Code 


The debugger provides two modes for displaying information: noscreen mode 
and screen mode. By default, when you start the debugger, you are in noscreen 
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mode, but you might find that it is easier to view source code in screen mode. 

The following sections briefly describe both modes. 

6.2.1 Noscreen Mode 

Noscreen mode is the default, line-oriented mode of displaying input and output. 
The interactive examples throughout this chapter, excluding Section 6.2.2, show 
noscreen mode. 

In noscreen mode, use the TYPE command to display one or more source lines. 
For example, the following command displays line 7 of the module in which 
execution is currently paused: 

DBG> TYPE 7 
module SWAP_ROUTINES 

7: TEMP := A; 

DBG> 

The display of source lines is independent of program execution. To display source 
code from a module (compilation unit) other than the one in which execution is 
currently paused, use the TYPE command with a path name to specify the 
module. For example, the following command displays lines 16 to 21 of module 
TEST: 

DBG> TYPE TEST\16:21 

Path names are discussed in more detail in Section 6.3.1, in conjunction with the 
STEP command. 

You can also use the EXAMINE/SOURCE command to display the source line for 
a routine or any other program location that is associated with an instruction. 

The debugger also displays source lines automatically when it suspends execution 
at a breakpoint or watchpoint or after a STEP command, or when a tracepoint is 
triggered (see Section 6.3). 

After displaying source lines at various locations in your program, you can 
redisplay the location at which execution is currently paused by pressing KP5. 

If the debugger cannot locate source lines for display, it issues a diagnostic 
message. Source lines might not be available for a variety of reasons. For 
example: 

• Execution is paused within a module that was compiled or linked without the 
/DEBUG qualifier. 

• Execution is paused within a system or shareable image routine for which no 
source code is available. 

• The source file was moved to a different directory after it was compiled (the 
location of source files is embedded in the object modules). In this case, use 
the SET SOURCE command to specify the new location. 

• The module might need to be set with the SET MODULE command. Module 
setting is explained in Section 6.5.1. 

To switch to noscreen mode from screen mode, press PF1 PF3 (or type SET 
MODE NOSCREEN). You can use the TYPE and EXAMINE/SOURCE commands 
in screen mode as well as noscreen mode. 
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6.2.2 Screen Mode 

Screen mode provides the easiest way to view your source code. To switch to 
screen mode, press PF3 (or type SET MODE SCREEN). In screen mode, by 
default the debugger splits the screen into three displays named SRC, OUT, and 
PROMPT, as shown in Figure 6-2. 


Figure 6-2 Default Screen Mode Display Configuration 



The SRC display shows the source code of the module in which execution 
is currently paused. An arrow in the left column points to the source line 
corresponding to the current value of the program counter (PC). The PC is a 
register that contains the memory address of the instruction to be executed next. 
The line numbers, which are assigned by the compiler, match those in a listing 
file. As you execute the program, the arrow moves down and the source code is 
scrolled vertically to center the arrow in the display. 

The OUT display captures the debugger’s output in response to the commands 
that you enter. The PROMPT display shows the debugger prompt, your input (the 
commands that you enter), debugger diagnostic messages, and program output. 

You can scroll both SRC and OUT to see whatever information might scroll 
beyond the display window’s edge. Press KP3 repeatedly as needed to select the 
display to be scrolled (by default, SRC is scrolled). Press KP8 to scroll up and 
KP2 to scroll down. Scrolling a display does not affect program execution. 

In screen mode, if the debugger cannot locate source lines for the routine in which 
execution is currently paused, it tries to display source lines in the next routine 
down on the call stack for which source lines are available. If the debugger can 
display source lines for such a routine, it issues the following message: 

%DEBUG-I-SOURCESCOPE, Source lines not available for .0\%PC. 

Displaying source in a caller of the current routine. 

DBG> 
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In such cases, the arrow in the SRC display identifies the line that contains code 
following the call statement in the calling routine. 

6.3 Controlling and Monitoring Program Execution 

This section explains how to perform the following tasks: 

• Start and resume program execution 

• Execute the program to the next source line, instruction, or other step unit 

• Determine where execution is currently paused 

• Use breakpoints to suspend program execution at points of interest 

• Use tracepoints to trace the execution path of your program through specified 
locations 

• Use watchpoints to monitor changes in the values of variables 

With this information you can pick program locations where you can then test 
and manipulate the contents of variables as described in Section 6.4. 

6.3.1 Starting or Resuming Program Execution 

Use the GO command to start or resume program execution. 

After it is started with the GO command, program execution continues until one 
of the following events occurs: 

• The program completes execution 

• A breakpoint is reached 

• A watchpoint is triggered 

• An exception is signaled 

• You press Ctrl/C 

With most programming languages, when you bring a program under debugger 
control, execution is initially paused directly at the beginning of the main 
program. Entering a GO command at this point quickly enables you to test for an 
infinite loop or an exception. 

If an infinite loop occurs during execution, the program does not terminate, so the 
debugger prompt does not reappear. To obtain the prompt, interrupt execution 
by pressing Ctrl/C (see Section 5.3.6). If you are using screen mode, the pointer 
in the source display indicates where execution stopped. You can also use the 
SHOW CALLS command to identify the currently active routine calls on the call 
stack (see Section 6.3.3). 

If an exception that is not handled by your program is signaled, the debugger 
interrupts execution at that point so that you can enter commands. You can then 
look at the source display and a SHOW CALLS display to find where execution is 
paused. 

The most common use of the GO command is in conjunction with breakpoints, 
tracepoints, and watchpoints, as described in Section 6.3.4, Section 6.3.5, and 
Section 6.3.6, respectively. If you set a breakpoint in the path of execution and 
then enter the GO command, execution is paused at that breakpoint. Similarly, if 
you set a tracepoint, execution is monitored through that tracepoint. If you set a 
watchpoint, execution is paused when the value of the watched variable changes. 
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6.3.2 Executing the Program by Step Unit 

Use the STEP command to execute the program one or more step units at a time. 

By default, a step unit is one line of source code. In the following example, the 
STEP command executes one line, reports the action ("stepped to . . . "), and 
displays the line number (27) and source code of the line to be executed next: 

DBG> STEP 

stepped to TEST\COUNT\%LINE 27 
27: X := X + 1; 

DBG> 

Execution is now paused at the first machine-code instruction for line 27 within 
routine COUNT of module TEST. 

When displaying a program symbol (for example, a line number, routine name, or 
variable name), the debugger always uses a path name. A path name consists 
of the symbol plus a prefix that identifies the symbol’s location. In the previous 
example, the path name is TEST\ COUNT\ %LINE 27. The leftmost element of 
a path name is the module name. Moving toward the right, the path name lists 
any successively nested routines and blocks that enclose the symbol. A backslash 
character (\ ) is used to separate elements (except when the language is Ada, 
where a period is used to parallel Ada syntax). 

A path name uniquely identifies a symbol of your program to the debugger. In 
general, you need to use path names in commands only if the debugger cannot 
resolve a symbol ambiguity in your program (see Section 6.5). Usually the 
debugger can determine the symbol you mean from its context. 

When using the STEP command, note that only those source lines for which code 
instructions were generated by the compiler are recognized as executable lines by 
the debugger. The debugger skips over any other lines—for example, comment 
lines. 

You can specify different stepping modes, such as stepping by instruction rather 
than by line (SET STEP INSTRUCTION). Also, by default, the debugger steps 
over called routines—execution is not paused within a called routine, although 
the routine is executed. By entering the SET STEP INTO command, you direct 
the debugger to suspend execution within called routines as well as within the 
routine in which execution is currently paused (SET STEP OVER is the default 
mode). 

6.3.3 Determining Where Execution Is Paused 

The SHOW CALLS command is useful when you are unsure where execution is 
paused during a debugging session (for example, after a Ctrl/C interruption). 

The command displays a traceback that lists the sequence of calls leading to the 
routine in which execution is paused. For each routine (beginning with the one in 
which execution is paused), the debugger displays the following information: 

• The name of the module that contains the routine 

• The name of the routine 

• The line number at which the call was made (or at which execution is paused, 
in the case of the current routine) 

• The corresponding PC value 
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4 ^4 


Alpha 


On VAX processors, the PC value is shown as a memory address relative to 
the nearest preceding symbol value (for example, a routine) and also as an 
absolute address. ♦ 

On Alpha processors, the PC is shown as a memory address relative to the 
first code address in the module and also as an absolute address. ♦ 

For example: 


DBG> SHOW CALLS 


module name 

routine name 

line 

rel PC 

abs PC 

*TEST 

PRODUCT 

18 

00000009 

0000063C 

*TEST 

COUNT 

47 

00000009 

00000647 

*MY PROG 

MY PROG 

21 

0000000D 

00000653 


DBG> 

This example indicates that execution is paused at line 18 of routine PRODUCT 
(in module TEST), which was called from line 47 of routine COUNT (in module 
TEST), which was called from line 21 of routine MY_PROG (in module MY_ 
PROG). 

6.3.4 Suspending Program Execution with Breakpoints 

The SET BREAK command enables you to select locations at which to suspend 
program execution (breakpoints). You can then enter commands to check the 
call stack, examine the current values of variables, and so on. You resume 
execution from a breakpoint with the GO or STEP commands. 

The following example shows a typical use of the SET BREAK command: 


DBG> SET BREAK COUNT 
DBG> GO 


break at routine PR0G2\C0UNT 

54: procedure COUNT(X,Y:INTEGER); 

DBG> 

In the example, the SET BREAK command sets a breakpoint on routine COUNT 
(at the beginning of the routine’s code); the GO command starts execution; when 
routine COUNT is encountered, execution is paused, the debugger announces that 
the breakpoint at COUNT has been reached ("break at . . . "), displays the source 
line (54) at which execution is paused, and prompts for another command. At 
this breakpoint, you can use the STEP command to step through routine COUNT 
and then use the EXAMINE command (discussed in Section 6.4.1) to check on the 
values of X and Y. 

When using the SET BREAK command, you can specify program locations using 
various kinds of address expressions (for example, line numbers, routine 
names, memory addresses, byte offsets). With high-level languages, you typically 
use routine names, labels, or line numbers, possibly with path names to ensure 
uniqueness. 

Routine names and labels should be specified as they appear in the source code. 
Line numbers can be derived from either a source code display or a listing file. 
When specifying a line number, use the prefix %LINE. Otherwise, the debugger 
interprets the line number as a memory location. For example, the following 
command sets a breakpoint at line 41 of the module in which execution is paused. 
The breakpoint causes the debugger to suspend execution at the beginning of 
line 41. 
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DBG> SET BREAK %LINE 41 

Note that you can set breakpoints only on lines that resulted in machine-code 
instructions. The debugger warns you if you try to do otherwise (for example, on 
a comment line). To pick a line number in a module other than the one in which 
execution is paused, you must specify the module’s name in a path name. For 
example: 

DBG> SET BREAK SCREEN_IO\%LINE 58 

You can also use the SET BREAK command with a qualifier, but no parameter, to 
break on every line, or on every CALL instruction, and so on. For example: 

DBG> SET BREAK/LINE 
DBG> SET BREAK/CALL 

You can set breakpoints on events, such as exceptions, or state transitions in 
tasking programs. 

You can conditionalize a breakpoint (with a WHEN clause) or specify that a list of 
commands be executed at the breakpoint (with a DO clause). 

To display the current breakpoints, enter the SHOW BREAK command. 

To deactivate a breakpoint, enter the DEACTIVATE BREAK command, and 
specify the program location exactly as you did when setting the breakpoint. 

This causes the debugger to ignore the breakpoint during program execution. 
However, you can activate it at a later time, for example, when you rerun the 
program (see Section 5.3.3). A deactivated breakpoint is listed as such in a 
SHOW BREAK display. 

To activate a breakpoint, use the ACTIVATE BREAK command. Activating a 
breakpoint causes it to take effect during program execution. 

The commands DEACTIVATE BREAK/ALL and ACTIVATE BREAK/ALL operate 
on all breakpoints and are particularly useful when rerunning a progr am 

To cancel a breakpoint, use the CANCEL BREAK command. A canceled 
breakpoint is no longer listed in a SHOW BREAK display. 

6.3.5 Tracing Program Execution with Tracepoints 

The SET TRACE command enables you to select locations for tracing the 
execution of your program (tracepoints), without stopping its execution. After 
setting a tracepoint, you can start execution with the GO command and then 
monitor the path of execution, checking for unexpected behavior. By setting a 
tracepoint on a routine, you can also monitor the number of times it is called. 

As with breakpoints, every time a tracepoint is reached, the debugger issues a 
message and displays the source line. But the program continues executing, and 
the debugger prompt is not displayed. For example: 

DBG> SET TRACE COUNT 
DBG> GO 

trace at routine PR0G2\C0UNT 

54: procedure COUNT(X,Y:INTEGER); 
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This is the only difference between a breakpoint and a tracepoint. When 
using the SET TRACE command, you specify address expressions, qualifiers, 
and optional clauses exactly as with the SET BREAK command. The 
commands SHOW TRACE, ACTIVATE TRACE, DEACTIVATE TRACE, and 
CANCEL TRACE operate on tracepoints in a manner similar to the corresponding 
commands for breakpoints (see Section 6.3.4). 

6.3.6 Monitoring Changes in Variables with Watchpoints 

The SET WATCH command enables you to specify program variables that the 
debugger monitors as your program executes. This process is called setting 
watchpoints. If the program modifies the value of a watched variable, the 
debugger suspends execution and displays information. The debugger monitors 
watchpoints continuously during program execution. (Note that you can also 
use the SET WATCH command to monitor arbitrary program locations, not just 
variables.) 

The technique you use to set watchpoints depends on your system (VAX or Alpha) 
and the type of variable (static or nonstatic). 

On VAX processors, you can set a watchpoint on a static variable by specifying 
the variable’s names with the SET WATCH command. Since a static variable 
is associated with the same memory address throughout program execution, this 
variable name is always meaningful. For example, the following command sets a 
watchpoint on the variable TOTAL: 

DBG> SET. WATCH TOTAL 

Subsequently, every time the program modifies the value of TOTAL, the 
watchpoint is triggered. 

The following example shows what happens when your program modifies the 
contents of this watched variable: 

DBG> SET WATCH TOTAL 
DBG> GO 


watch of SCREEN_I0\T0TAL at SCREEN_IO\%LINE 13 
13: TOTAL = TOTAL + 1; 

old value: 16 
new value: 17 

break at SCREEN_IO\%LINE 14 
14: POP(TOTAL); 

DBG> 

In this example, a watchpoint is set on the variable TOTAL and execution is 
started. When the value of TOTAL changes, execution is paused. The debugger 
announces the event ("watch of . . . "), identifying where TOTAL changed (the 
beginning of line 13) and the associated source line. The debugger then displays 
the old and new values and announces that execution has been paused at the 
beginning of the next line (14). Finally, the debugger prompts for another 
command. When a change in a variable occurs at a point other than the 
beginning of a source line, the debugger gives the line number plus the byte 
offset from the beginning of the line. ♦ 

On VAX processors and Alpha processors, you can set a watchpoint on a nonstatic 
variable by setting a tracepoint on the defining routine and specifying a DO 
clause to set the watchpoint whenever execution reaches the tracepoint. Since 
a nonstatic variable is allocated on the stack or in a register and exists only 
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when its defining routine is active (on the call stack), the variable name is not 
always meaningful in the way that a static variable name is. 

In the following example, a watchpoint is set on the nonstatic variable Y in 
routine ROUT3. After the tracepoint is triggered, the WPTTRACE message 
indicates that the nonstatic watchpoint is set, and the watchpoint is triggered 
when the value of Y changes. For example: 

DBG> SET TRACE/NOSOURCE R0UT3 DO (SET WATCH Y) 

DBG> GO 


trace at routine MOD4\ROOT3 

IDEBUG-I-WPTTRACE, nonstatic watchpoint, tracing every 
instruction 


watch of MOD4\ROUT3\Y at MOD4\ROOT3\%LINE 16 
16: Y := 4 

old value: 3 

new value: 4 

break at MOD4\ROUT3\%LINE 17 
17: SWAP(X,Y); 

DBG> 


Alpha 


When execution returns to the calling routine, the nonstatic variable is no 
longer active, so the debugger automatically cancels the watchpoint and issues a 
message to that effect. 

On Alpha processors, the debugger treats all watchpoints as nonstatic 
watchpoints. ♦ 

The commands SHOW WATCH, ACTIVATE WATCH, DEACTIVATE WATCH, 
and CANCEL WATCH operate on watchpoints in a manner similar to the 
corresponding commands for breakpoints (see Section 6.3.4). However, a nonstatic 
watchpoint exists only as long as execution remains within the scope of the 
variable being watched. 


6.4 Examining and Manipulating Program Data 

This section explains how to use the EXAMINE, DEPOSIT, and EVALUATE 
commands to display and modify the contents of variables and evaluate 
expressions. Before you can examine or deposit into a nonstatic variable, as 
defined in Section 6.3.6, its defining routine must be active. 


6.4.1 Displaying the Value of a Variable 

To display the current value of a variable, use the EXAMINE command. It has 
the following syntax: 


EXAMINE variable-name 

The debugger recognizes the compiler-generated data type of the variable you 
specify and retrieves and formats the data accordingly. The following examples 
show some uses of the EXAMINE command. 

Examine a string variable: 

DBG> EXAMINE EMPLOYEE_NAME 

PAYROLL\EMPLOYEE_NAME: "Peter C. Lombardi" 

DBG> 
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Examine three integer variables: 

DBG> EXAMINE WIDTH, LENGTH, AREA 
SIZE\WIDTH: 4 

SIZE\LENGTH: 7 
SIZE\AREA: 28 

DBG> 

Examine a two-dimensional array of real numbers (three per dimension): 

DBG> EXAMINE REAL_ARRAY 
P ROG 2\REAL_ARRAY 

(1.1) : 27.01000 

(1.2) : 31.00000 

(1,3): 12.48000 

(2,1): 15.08000 

(2.2) : 22.30000 

(2.3) : 18.73000 

DBG> 

Examine element 4 of a one-dimensional array of characters: 

DBG> EXAMINE CHAR_ARRAY(4) 

PROG2\CHAR_ARRAY(4): 'm' 

DBG> 

Examine a record variable (COBOL example): 

DBG> EXAMINE PART 
INVENTORY\PART: 

ITEM: "WF-1247" 

PRICE: 49.95 

IN_STOCK: 24 

DBG> 

Examine a record component (COBOL example): 

DBG> EXAMINE IN_STOCK OF PART 
INVENTORY\IN-STOCK of PART: 

IN_STOCK: 24 

DBG> 

You can use the EXAMINE command with any kind of address expression (not 
just a variable name) to display the contents of a program location. The debugger 
associates certain default data types with untyped locations. You can override 
the defaults for typed and untyped locations if you want the data interpreted and 
displayed in some other data format. 

6.4.2 Assigning a Value to a Variable 

To assign a new value to a variable, use the DEPOSIT command. It has the 
following syntax: 

DEPOSIT variable-name = value 

The DEPOSIT command is like an assignment statement in most programming 
languages. 

In the following examples, the DEPOSIT command assigns new values to 
different variables. The debugger checks that the value assigned, which can be a 
language expression, is consistent with the data type and dimensional constraints 
of the variable. 
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Deposit a string value (it must be enclosed in quotation marks (") or apostrophes 
('): 

DBG> DEPOSIT PART_NUMBER = "WG-7619.3-84" 

Deposit an integer expression: 

DBG> DEPOSIT WIDTH = CURRENT_WIDTH +10 

Deposit element 12 of an array of characters (you cannot deposit an entire array 
aggregate with a single DEPOSIT command, only an element): 

DBG> DEPOSIT C_ARRAY(12) := 'K' 

Deposit a record component (you cannot deposit an entire record aggregate with a 
single DEPOSIT command, only a component): 

DBG> DEPOSIT EMPLOYEE.ZIPCODE = 02172 

Deposit an out-of-bounds value (X was declared as a positive integer): 

DBG> DEPOSIT X = -14 

%DEBUG-I-IVALOUTBNDS, value assigned is out of bounds 
at or near DEPOSIT 

As with the EXAMINE command, you can specify any kind of address expression 
(not just a variable name) with the DEPOSIT command. You can override the 
defaults for typed and untyped locations if you want the data interpreted in some 
other data format. 

6.4.3 Evaluating Language Expressions 

To evaluate a language expression, use the EVALUATE command. It has the 
following syntax: 

EVALUATE language-expression 

The debugger recognizes the operators and expression syntax of the currently 
set language. In the following example, the value 45 is assigned to the integer 
variable WIDTH; the EVALUATE command then obtains the sum of the current 
value of WIDTH and 7: 

DBG> DEPOSIT WIDTH := 45 
DBG> EVALUATE WIDTH + 7 
52 

DBG> 

In the next example, the values TRUE and FALSE are assigned to the Boolean 
variables WILLING and ABLE, respectively; the EVALUATE command then 
obtains the logical conjunction of these values: 

DBG> DEPOSIT WILLING := TRUE 
DBG> DEPOSIT ABLE := FALSE 
DBG> EVALUATE WILLING AND ABLE 
False 
DBG> 
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6.5 Controlling Access to Symbols in Your Program 

To have full access to the symbols that are associated with your program (variable 
names, routine names, source code, line numbers, and so on), you must compile 
and link the program using the /DEBUG qualifier, as explained in Section 5.2. 

Under these conditions, the way in which the debugger handles these symbols is 
transparent to you in most cases. However, the following two areas might require 
action: 

• Setting and canceling modules 

• Resolving symbol ambiguities 

6.5.1 Setting and Canceling Modules 

To facilitate symbol searches, the debugger loads symbol information from the 
executable image into a run-time symbol table (RST), where that information can 
be accessed efficiently. Unless symbol information is in the RST, the debugger 
does not recognize or properly interpret the associated symbols. 

Because the RST takes up memory, the debugger loads it dynamically, 
anticipating what symbols you might want to reference in the course of program 
execution. The loading process is called module setting, because all symbol 
information for a given module is loaded into the RST at one time. 

Initially, only the module containing the image transfer address is set. 
Subsequently, whenever execution of the program is interrupted, the debugger 
sets the module that contains the routine in which execution is paused. This 
enables you to reference the symbols that should be visible at that location. 

If you try to reference a symbol in a module that has not been set, the debugger 
warns you that the symbol is not in the RST. For example: 

DBG> EXAMINE K 

%DEBUG-W-NOSYMBOL, symbol 'K' is not in symbol table 
DBG> 

You must use the SET MODULE command to set the module containing that 
symbol explicitly. For example: 

DBG> SET MODULE M0D3 
DBG> EXAMINE K 
MOD3\ROUT2\K: 26 
DBG> 

The SHOW MODULE command lists the modules of your program and identifies 
which modules are set. 

Dynamic module setting can slow the debugger down as more and more modules 
are set. If performance becomes a problem, you can use the CANCEL MODULE 
command to reduce the number of set modules, or you can disable dynamic 
module setting by entering the SET MODE NODYNAMIC command (SET MODE 
DYNAMIC enables dynamic module setting). 
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6.5.2 Resolving Symbol Ambiguities 

Symbol ambiguities can occur when a symbol (for example, a variable name X) is 
defined in more than one routine or other program unit. 

In most cases, the debugger resolves symbol ambiguities automatically. First, 
it uses the scope and visibility rules of the currently set language. In addition, 
because the debugger permits you to specify symbols in arbitrary modules (to set 
breakpoints and so on), the debugger uses the ordering of routine calls on the call 
stack to resolve symbol ambiguities. 

If the debugger cannot resolve a symbol ambiguity, it issues a message. For 
example: 

DBG> EXAMINE Y 

%DEBUG-W-NOUNIQUE, symbol 'Y' is not unique 
DBG> 

You can then use a path-name prefix to uniquely specify a declaration of the 
given symbol. First, use the SHOW SYMBOL command to identify all path 
names associated with the given symbol (corresponding to all declarations of that 
symbol) that are currently loaded in the RST. Then use the desired path-name 
prefix when referencing the symbol. For example: 

DBG> SHOW SYMBOL Y 

data MOD7\ROOT3\BLOCKl\Y 

data MOD4\ROUT2\Y 

DBG> EXAMINE MOD4\ROUT2\Y 

MOD4\ROUT2\Y: 12 

DBG> 

If you need to refer to a particular declaration of Y repeatedly, use the SET 
SCOPE command to establish a new default scope for symbol lookup. Then, 
references to Y without a path-name prefix specify the declaration of Y that’is 
visible in the new scope. For example: 

DBG> SET SCOPE MOD4\ROOT2 
DBG> EXAMINE Y 
MOD4\ROUT2\Y: 12 
DBG> 

To display the current scope for symbol lookup, use the SHOW SCOPE command. 
To restore the default scope, use the CANCEL SCOPE command. 

6.6 Sample Debugging Session 

This section walks you through a debugging session with a simple FORTRAN 
program that contains a logic error (see Example 6-1). Compiler-assigned line 
numbers have been added in the example so that you can identify the source lines 
referenced in the discussion. 

The program, called SQUARES, performs the following functions: 

1. Reads a sequence of integer numbers from a data file and saves these 
numbers in the array INARR (lines 4 and 5). 

2. Enters a loop in which it copies the square of each nonzero integer into 
another array OUTARR (lines 8 through 13). 
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3. Prints the number of nonzero elements in the original sequence and the 
square of each such element (lines 16 through 21). 


Example 6-1 Sample Program SQUARES 

1: INTEGER INARR(20), OOTARR(20) 

2: C 

3: C —Read the input array from the data file. 

4: OPEN(UNIT=8, FILE='DATAFILE.DAT', STATUS='OLD') 

5: READ(8,*) N, (INARR(I), 1=1,N) 

6: C 

7: C —Square all nonzero elements and store in OUTARR. 

8: K = 0 

9: DO 10 I = 1, N 

10: IF(INARR(I) .NE. 0) THEN 

11 : OUTARR(K) = INARR(I)**2 

12: ENDIF 

13: 10 CONTINUE 

14: C 

15: C —Print the squared output values. Then stop. 

16: PRINT 20, K 

17: 20 FORMAT(' Number of nonzero elements is',14) 

18: DO 40 I = 1, K 

19: PRINT 30, I, OUTARR(I) 

20: 30 FORMAT(' Element',14,' has value',16) 

21: 40 CONTINUE 

22: END 

When you run SQUARES, it produces the following output, regardless of the 
number of nonzero elements in the data file: 

$ RUN SQUARES 

Number of nonzero elements is 0 

The error in the program is that variable K, which keeps track of the current 
index into OUTARR, is not incremented in the loop on lines 9 through 13. The 
statement K = K + 1 should be inserted just before line 11. 

Example 6-2 shows how to start the debugging session and then how to use the 
debugger to find the error. Comments, keyed to the callouts, follow the example. 

Example 6-2 Sample Debugging Session Using Program SQUARES 

$ FORTRAN/DEBUG/NOOPTIMIZE SQUARES O 
$ LINK/DEBUG SQUARES © 

$ SHOW LOGICAL DBG$PROCESS © 

%SHOW-S-NOTRAN, no translation for logical name DBG$PROCESS 
$ DEBUG/KEEP © 

Debugger Banner and Version Number 
DBG> RUN SQUARES © 

%DEBUG-I-INITIAL, language is FORTRAN, module set to SQUARESSMAIN 
DBG> STEP 4 © 

stepped to SQUARES$MAIN\%LINE 9 
9: DO 10 I = 1, N 

DBG> EXAMINE N,K © 

SQUARES$MAIN\N: 9 

SQUARES$MAIN\K: 0 


(continued on next page) 
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Example 6-2 (Cont.) Sample Debugging Session Using Program SQUARES 

DBG> STEP 2 © 

stepped to SQUARES$MAIN\%LINE 11 

11: OUTARR(K) = INARR(I)**2 

DBG> EXAMINE I,K © 

SQUARES$MAIN\I: 1 

SQUARES$MAIN\K: 0 

DBG> DEPOSIT K = 1 © 

DBG> SET TRACE/SILENT %LINE 11 DO (DEPOSIT K = K + 1) © 

DBG> GO © 

Number of nonzero elements is 4 
Element 1 has value 16 

Element 2 has value 36 

Element 3 has value 9 

Element 4 has value 49 

%DEBUG-I-EXITSTATUS, is 'SYSTEM-S-NORMAL, normal successful completion' 

DBG> SPAWN © 

$ EDIT SQUARES.FOR © 


10: IF(INARR(I) .NE. 0) THEN 

11: K = K + 1 

12: OUTARR(K) = INARR(I)**2 

13: ENDIF 


$ FORTRAN/DEBUG/NOOPTIMIZE SQUARES © 

$ LINK/DEBUG SQUARES 
$ LOGOUT © 

DBG> RUN SQUARES © 

%DEBUG-I-INITIAL, language is FORTRAN, module set to SQUARES$MAIN 
DBG> SET BREAK %LINE 12 DO (EXAMINE I,K) © 

DBG> GO © 

SQUARES$MAIN\I: 1 

SQUARES$MAIN\K: 1 

DBG> GO 


SQUARES$MAIN\I: 2 
SQUARES$MAIN\K: 2 
DBG> GO 

SQUARES$MAIN\I: 4 
SQUARES$MAIN\K: 3 
DBG> EXIT © 

$ 


The following comments apply to the callouts in Example 6-2. Example 6-1 
shows the program that is being debugged. 

® The /DEBUG qualifier on the DCL FORTRAN command directs the compiler 
to write the symbol information associated with SQUARES into the object 
module, SQUARES.OBJ, in addition to the code and data for the program. 

The /NOOPTIMIZE qualifier disables optimization by the FORTRAN 
compiler, which ensures that the executable code matches the source code 
of the program. Debugging optimized code can be confusing because the 
contents of some program locations might be inconsistent with what you 
would expect from viewing the source code. 

© The /DEBUG qualifier on the DCL LINK command causes the linker to 
include all symbol information that is contained in SQUARES.OBJ in the 
executable image. 
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© You can start the debugger in either the default configuration or the 

multiprocess configuration, depending on the definition of the logical name 
DBG$PROCESS. In this example, the SHOW LOGICAL DBG$PROCESS 
command shows that DBG$PROCESS is undefined, indicating that the 
default configuration is in effect. This is the correct configuration for a 
program like SQUARES that runs in only one process. 

© The DCL command DEBUG/KEEP starts the debugger, which displays 
its banner and the debugger prompt, DBG>. You can now enter debugger 
commands. 

© The debugger command RUN SQUARES brings the program SQUARES 
under debugger control. The informational message identifies the source 
language of the program and the name of the main program unit (FORTRAN 
and SQUARES, respectively, in this example). 

Execution is initially paused at the start of the main program unit (line 1 of 
SQUARES, in this example). 

© You decide to test the values of variables N and K after the READ statement 
has been executed and the value 0 has been assigned to K. 

The command STEP 4 executes 4 source lines of the program. Execution is 
now paused at line 9. Note that the STEP command ignores source lines that 
do not result in executable code; also, by default, the debugger identifies the 
source line at which execution is paused. 

© The command EXAMINE N, K displays the current values of N and K. Their 
values are correct at this point in the execution of the program. 

© The command STEP 2 executes the program into the loop that copies and 
squares all nonzero elements of INARR into OUTARR. 

© The command EXAMINE I,K displays the current values of I and K. 

I has the expected value 1, but K has the value 0 instead of 1, which is the 
expected value. Now you can see the error in the program: K should be 
incremented in the loop just before it is used in line 11. 

© The DEPOSIT command assigns K the value it should have now: 1. 

<D The SET TRACE command is now used to patch the program so that the 
value of K is incremented automatically in the loop. The command sets a 
tracepoint that triggers every time execution reaches line 11: 

• The /SILENT qualifier suppresses the "trace at" message that would 
otherwise appear each time line 11 is executed. 

• The DO clause issues the DEPOSIT K = K + 1 command every time the 
tracepoint is triggered. 

© To test the patch, the GO command starts execution from the current location. 

The program output shows that the patched program works properly. The 
EXITSTATUS message shows that the program executed to completion. 

© The SPAWN command spawns a subprocess to return control temporarily to 
DCL level (without ending the debugging session) so that you can correct the 
source file and recompile and relink the program. 

© The EDIT command invokes an editor and the source file is edited to add 
K = K + 1 after line 10, as shown. (Compiler-assigned line numbers have 
been added to clarify the example.) 
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© The revised program is compiled and linked. 

© The LOGOUT command terminates the spawned subprocess and returns 
control to the debugger. 

® The (debugger) command RUN SQUARES brings the revised program under 
debugger control so that its correct execution can be verified. 

© The SET BREAK command sets a breakpoint that triggers every time line 
12 is executed. The DO clause displays the values of I and K automatically 
when the breakpoint triggers. 

© The GO command starts execution. 

At the first breakpoint, the value of K is 1, indicating that the program is 
running correctly so far. Each additional GO command shows the current 
values of I and K. After two more GO commands, K is now 3, as expected, 
but note that I is 4. The reason is that one of the INARR elements was 0 so 
that lines 11 and 12 were not executed (and K was not incremented) for that 
iteration of the DO loop. This confirms that the program is running correctly. 

© The EXIT command ends the debugging session and returns control to DCL 
level. 
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Controlling and Monitoring Program Execution 


This chapter describes how to control and monitor program execution while 
debugging by using the following techniques: 

• Executing the program by step unit 

• Suspending and tracing execution with breakpoints and tracepoints 

• Monitoring changes in variables and other program locations with 
watchpoints 

The following related functions are discussed in Chapter 6: 

• Starting or resuming program execution with the GO command (Section 6.3.1) 

• Monitoring where execution is currently paused with the SHOW CALLS 
command (Section 6.3.3) 

This chapter includes information that is common to all programs. For more 
information: 

See Chapter 14 for additional information specific to multiprocess programs. 

See Chapter 15 for additional information specific to vectorized programs. ♦ 

See Chapter 16 for additional information specific to tasking (multithread) 
programs. 

For information about rerunning your program or running another program from 
the current debugging session, see Section 5.3.3 and Section 5.3.4. 

7.1 Commands Used to Execute the Program 

Only four debugger commands are directly associated with program execution: 

GO 

STEP 

CALL 

EXIT (if your program has exit handlers) 

As explained in Section 6.3.1 and Section 6.3.2, GO and STEP are the basic 
commands for starting and resuming program execution. The STEP command is 
discussed further in Section 7.2. 

During a debugging session, routines are executed as they are called during the 
execution of a program. The CALL command enables you to arbitrarily call and 
execute a routine that was linked with your program. This command is discussed 
in Section 12.7. 

The EXIT command was discussed in Section 5.3.5, in conjunction with ending a 
debugging session. Because it executes any exit handlers in your program, it is 
also useful for debugging exit handlers (see Section 13.6). 
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When using any of these four commands, note that program execution can be 
interrupted or stopped by any of the following events: 

• The program terminates 

• A breakpoint is reached 

• A watchpoint is triggered 

• An exception is signaled 

• You press Ctrl/C 

7.2 Executing the Program by Step Unit 

The STEP command (probably the most frequently used debugger command) 
enables you to execute your program in small increments called step units. 

By default, a step unit is an executable line of source code. In the following 
example, the STEP command executes one line, reports the action ("stepped 
to . . . •'), and displays the line number (27) and source code of the next line to be 
executed: 

DBG> STEP 

stepped to TEST\COUNT\%LINE 27 
27: X := X + 1; 

DBG> 

Execution is now paused at the first machine-code instruction for line 27 of 
module TEST. Line 27 is in COUNT, a routine within module TEST. 

The STEP command can also execute several source lines at a time. If you specify 
a positive integer as a parameter, the STEP command executes that number of 
lines. In the following example, the STEP command executes the next three lines. 

DBG> STEP 3 

stepped to TEST\COUNT\%LINE 34 
34: SWAP (X, Y) ; 

DBG> 

Note that only those source lines for which code instructions were generated by 
the compiler are recognized as executable lines by the debugger. The debugger 
skips over any other lines—for example, comment lines. Also, if a line has more 
than one statement on it, the debugger executes all the statements on that line 
as part of the single step. 

Source lines are displayed by default after stepping if they are available for the 
module being debugged. Source lines are not available if you are stepping in code 
that has not been compiled or linked with the /DEBUG qualifier (for example, 
a shareable image routine). If source lines are available, you can control their 
display with the SET STEP [NOJSOURCE command and the /[NOJSOURCE 
qualifier of the STEP command. For information about how to control the display 
of source code in general and in particular after stepping, see Chapter 10. 

7.2.1 Changing the STEP Command Behavior 

You can change the default behavior of the STEP command in two ways: 

• By specifying a STEP command qualifier—for example, STEP/INTO 

• By establishing a new default qualifier with the SET STEP command—for 
example, SET STEP INTO 
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In the following example, the STEP/INTO command steps into a called routine 
when the program counter (PC) is at a call statement. The debugger displays 
the source line identifying the routine PRODUCT, which is called from routine 
COUNT of module TEST: 

DBG> STEP/INTO 

stepped to routine TEST\PRODUCT 

6: function PRODUCT(X,Y : INTEGER) return INTEGER is 

DBG> 

After the STEP/INTO command executes, subsequent STEP commands revert to 
the default behavior. 

In contrast, the SET STEP command enables you to establish new defaults 
for the STEP command. These defaults remain in effect until another SET 
STEP command is entered. For example, the SET STEP INTO command causes 
subsequent STEP commands to behave like STEP/INTO (SET STEP LINE causes 
subsequent STEP commands to behave like STEP/LINE). 

There is a SET STEP command parameter for each STEP command qualifier. 

You can override the current STEP command defaults for the duration of a single 
STEP command by specifying other qualifiers. Use the SHOW STEP command to 
identify the current STEP command defaults. 

7.2.2 Stepping Into and Over Routines 

By default, when the PC is at a call statement and you enter the STEP command, 
the debugger steps over the called routine. Although the routine is executed, 
execution is not paused within the routine but, rather, on the beginning of the 
line that follows the call statement. When stepping by instruction, execution is 
paused on the instruction that follows a called routine’s return instruction. 

To step into a called routine when the PC is at a call statement, enter the 
STEP/INTO command. The following example shows how to step into the routine 
PRODUCT, which is called from routine COUNT of module TEST: 

DBG> STEP 

stepped to TEST\COUNT\%LINE 18 

18: AREA := PRODUCT(LENGTH, WIDTH); 

DBG> STEP/INTO 

stepped to routine TEST\PRODUCT 

6: function PRODUCT(X,Y : INTEGER) return INTEGER is 

DBG> 

To return to the calling routine from any point within the called routine, use 
the STEP/RETURN command. It causes the debugger to step to the return 
instruction of the routine being executed. A subsequent STEP command brings 
you back to the statement that follows the routine call. For example: 

DBG> STEP/RETURN 

stepped on return from TEST\PRODUCT\%LINE 11 to TEST\PRODUCT\%LINE 15+4 
15: end PRODUCT; 

DBG> STEP 

Stepped to TEST\COUNT\%LINE 19 

19: LENGTH := LENGTH + 1; 

DBG> 

To step into several routines, enter the SET STEP INTO command to change the 
default behavior of the STEP command from STEP/OVER to STEP/INTO: 

DBG> SET STEP INTO 
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As a result of this command, when the PC is at a call statement, a STEP 
command suspends execution within the called routine. If you later want to step 
over routine calls, enter the SET STEP OVER command. 

When SET STEP INTO is in effect, you can qualify the kinds of called routines 
that the debugger is stepping into by specifying any of the following parameters 
with the SET STEP command: 

• [NO]JSB—Controls whether to step into routines called by JSB instructions. 
(VAX processors only) ♦ 

• [NOISHARE—Controls whether to step into called routines in shareable 
images. 

• [NO]SYSTEM—Controls whether to step into called system routines. 

These parameters make it possible to step into application-defined routines and 
automatically step over system routines, and so on. For example, the following 
command directs the debugger to step into called routines in user space only. The 
debugger steps over routines in system space and in shareable images. 

DBG> SET STEP INTO,NOSYSTEM,NOSHARE 

7.3 Suspending and Tracing Execution with Breakpoints and 
Tracepoints 

This section discusses using the SET BREAK and SET TRACE commands to, 
respectively, suspend and trace program execution. The commands are discussed 
together because of their similarities. 

SET BREAK Command Overview 

The SET BREAK command lets you specify program locations or events at which 
to suspend program execution (breakpoints). After setting a breakpoint, you can 
start or resume program execution with the GO command, letting the program 
run until the specified location or condition is reached. When the breakpoint 
is triggered, the debugger suspends execution, identifies the breakpoint, and 
displays the DBG> prompt. You can then enter debugger commands—for 
example, to determine where you are (with the SHOW CALLS command), step 
into a routine, examine or modify variables, and so on. 

The syntax of the SET BREAK command is as follows: 

SET BREAK [/qualified . .. ]] [address-expressiori, ... ]] 

[WHEN ( conditional-expression )] 

[DO (command[\ ...])] 

The following example shows a typical use of the SET BREAK command and 
shows the general default behavior of the debugger at a breakpoint. 

In this example, the SET BREAK command sets a breakpoint on routine COUNT 
(at the beginning of the routine’s code). The GO command starts execution. When 
routine COUNT is encountered, execution is paused, the debugger announces that 
the breakpoint at COUNT has been reached ("break at . . . "), displays the source 
line (54) where execution is paused, and prompts for another command: 
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DBG> SET BREAK COUNT 
DBG> GO 


break at routine PR0G2\C0UNT 

54: procedure COUNT(X,Y:INTEGER); 

DBG> 

SET TRACE Command Overview 

The SET TRACE command lets you select program locations or events for tracing 
the execution of your program without stopping its execution (tracepoints). After 
setting a tracepoint, you can start execution with the GO command and then 
monitor that location, checking for unexpected behavior. By setting a tracepoint 
on a routine, you can also monitor the number of times it is called. 

The debugger’s default behavior at a tracepoint is identical to that at a 
breakpoint, except that program execution continues past a tracepoint. Thus, 
the DBG> prompt is not displayed when a tracepoint is reached and announced 
by the debugger. 

Except for the command name, the syntax of the SET TRACE command is 
identical to that of the SET BREAK command: 

SET TRACE[/qua//7/e/[ ... ]] [address-expression[, ... ]] 

[WHEN ( conditional-expression )] 

[DO ( command^ ; ...])] 

The SET TRACE and SET BREAK commands have the same qualifiers. When 
using the SET TRACE command, you specify address expressions, qualifiers, and 
the optional WHEN and DO clauses exactly as with the SET BREAK command. 

Unless you use the /TEMPORARY qualifier on the SET BREAK or SET TRACE 
command, breakpoints and tracepoints remain in effect until you: 

• Deactivate or cancel them (see Section 7.3.6) 

• Rerun the program with the RERUN/NOSAVE command (see Section 5.3.3) 

• Run a new program (see Section 5.3.4) or end the debugging session 
(Section 5.3.5) 

To identify all of the breakpoints or tracepoints that are currently set use the 
SHOW BREAK or SHOW TRACE command. 

To deactivate, activate, or cancel breakpoints or tracepoints, use the following 
commands (see Section 7.3.6): 

DEACTIVATE BREAK, DEACTIVATE TRACE 
ACTIVATE BREAK, ACTIVATE TRACE 
CANCEL BREAK, CANCEL TRACE 

The following sections describe how to specify program locations and events with 
the SET BREAK and SET TRACE commands. 
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7.3.1 Setting Breakpoints or Tracepoints on Individual Program Locations 

To set a breakpoint or a tracepoint on a particular program location, specify an 
address expression with the SET BREAK or SET TRACE command. 

Fundamentally, an address expression specifies a memory address or a register. 
Because the debugger understands the symbols associated with your program, 
the address expressions you typically use with the SET BREAK or SET TRACE 
command are routine names, labels, or source line numbers rather than memory 
addresses—the debugger converts these symbols to addresses. 

7.3.1.1 Specifying Symbolic Addresses 

__ Note --- 

In some cases, when using the SET BREAK or SET TRACE command 
with a symbolic address expression, you might need to set a module or 
specify a scope or a path name. Those concepts are described in detail in 
Chapter 9. The examples in this section assume that all modules are set 
and that all symbols referenced are uniquely defined, unless otherwise 
indicated. 


The following examples show how to set a breakpoint on a routine (SWAP) and a 
tracepoint on a label (LOOP1): 

DBG> SET BREAK SWAP 
DBG> SET TRACE L00P1 

The next command sets a breakpoint on the return instruction of routine 
SWAP. Breaking on the return instruction of a routine lets you inspect the 
local environment (for example, to obtain the values of local variables) while the 
routine is still active. 

DBG> SET BREAK/RETURN SWAP 

Some languages, for example FORTRAN, use numeric labels. To set a breakpoint 
or a tracepoint on a numeric label, you must precede the number with the built-in 
symbol %LABEL. Otherwise, the debugger interprets the number as a memory 
address. For example, the following command sets a tracepoint on label 20: 

DBG> SET TRACE %LABEL 20 

You can set a breakpoint or a tracepoint on a line of source code by specifying the 
line number preceded by the built-in symbol %LINE. The following command sets 
a breakpoint on line 14: 

DBG> SET BREAK %LINE 14 

The previous breakpoint causes execution to pause on the first instruction of line 
14. You can set a breakpoint or a tracepoint only on lines for which the compiler 
generated instructions (lines that resulted in executable code). If you specify a 
line number that is not associated with an instruction, such as a comment line or 
a statement that declares but does not initialize a variable, the debugger issues a 
diagnostic message. For example: 

DBG> SET BREAK %LINE 6 

%DEBUG-I-LINEINFO, no line 6, previous line is 5, next line is 8 
%DEBUG-E-NOSYMBOL, symbol 'ILINE 6' is not in the symbol table 
DBG> 

The previous messages indicate that the compiler did not generate instructions 
for lines 6 or 7 in this case. 
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Some languages allow more than one statement on a line. In such cases, you 
can use statement numbers to differentiate among statements on the same line. 
A statement number consists of a line number, followed by a period (.), and a 
number indicating the statement. The syntax is as follows: 

%LIN E line-number.statement-number 

For example, the following command sets a tracepoint on the second statement of 
line 38: 

DBG> SET TRACE ILINE 38.2 

When searching for symbols that you reference in commands, the debugger 
uses the conventions described in Section 9.3.1. That is, it first looks within the 
module where execution is currently paused, then in other scopes associated 
with routines on the call stack, and so on. Therefore, to specify a symbol that is 
defined in more than one module, such as a line number, you might need to use 
a path name. For example, the following command sets a tracepoint on line 27 of 
module MOD4: 


DBG> SET TRACE M0D4ULINE 27 

Remember the symbol lookup conventions when specifying a line number in 
debugger commands. If that line number is not defined in the module where 
execution is paused (because it is not associated with an instruction), the 
debugger uses the symbol lookup conventions to locate another module where 
the line number is defined. 

When specifying address expressions, you can combine symbolic addresses with 
byte offsets. Thus, you can set a breakpoint or a tracepoint on a particular 
instruction by specifying its line number and the byte offset from the beginning of 
that line to the first byte of the instruction. For example, the next command sets 
a breakpoint on the address that is five bytes beyond the beginning of line 23: 

DBG> SET BREAK ILINE 23+5 


7.3.1.2 Specifying Locations in Memory 

To set a breakpoint or a tracepoint on a location in memory, specify its numerical 
address in the currently set radix. The default radix for both data entry and 
display is decimal for most languages. 

0n VAX processors, the exceptions are BLISS and MACRO-32, which have a 
default radix of hexadecimal. ♦ 


Alpha 


On Alpha processors, the exceptions are BLISS, MACRO-32, and MACRO-64, 
which have a default radix of hexadecimal. ♦ 


For example, the following command sets a breakpoint at address 2753, decimal 
or at address 2753, hexadecimal: 


DBG> SET BREAK 2753 


You can specify a radix when you enter an individual integer literal (such as 
2753) by using one of the built-in symbols %BIN, %OCT, %DEC, or %HEX. For 
example, in the following command line the symbol %HEX specifies that 2753 
should be treated as a hexadecimal integer: 


DBG> SET BREAK %HEX 2753 


Note that when specifying a hexadecimal number that starts with a letter rather 
than a number, you must add a leading 0. Otherwise, the debugger tries to 
interpret the entity specified as a symbol declared in your program. 
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For additional information about specifying radixes and about the built-in 
symbols %BIN, %DEC, %HEX, and %OCT, see Section 8.1.9 and Appendix B. 

If a breakpoint or a tracepoint was set on a numerical address that corresponds 
to a symbol in your program, the SHOW BREAK or SHOW TRACE command 
identifies the breakpoint symbolically. 

7.3.1.3 Obtaining and Symbolizing Memory Addresses 

Use the EVALUATE/ADDRESS command to determine the memory address 
associated with a symbolic address expression, such as a line number, routine 
name, or label. For example: 

DBG> EVALOATE/ADDRESS SWAP 
1536 

DBG> EVALOATE/ADDRESS %LINE 26 

1629 

DBG> 

The address is displayed in the current radix. You can specify a radix qualifier to 
display the address in another radix. For example: 

DBG> EVALUATE/ADDRESS/HEX %LINE 26 

0000065D 

DBG> 

The SYMBOLIZE command does the reverse of EVALUATE/ADDRESS. It 
converts a memory address into its symbolic representation (including its path 
name) if such a representation is possible. Chapter 9 explains how to control 
symbolization. See Section 8.1.10 for more information about obtaining and 
symbolizing addresses. 

7.3.2 Setting Breakpoints or Tracepoints on Lines or Instructions 

The following SET BREAK and SET TRACE command qualifiers cause the 
debugger to break on or trace every source line or every instruction of a particular 
class: 

/LINE 

/BRANCH 

/CALL 

/INSTRUCTION 
/INSTRUCTION=(opcorfe[, . . . ]) 

When using these qualifiers, do not specify an address expression. 

For example, the following command causes the debugger to break on the 
beginning of every source line encountered during execution: 

DBG> SET BREAK/LINE 

The instruction-related qualifiers are especially useful for opcode tracing, which 
is the tracing of all instructions or the tracing of a class of instructions. The next 
command causes the debugger to trace every branch instruction encountered (for 
example BEQL, BGTR, and so on): 

DBG> SET TRACE/BRANCH 

Note that opcode tracing slows program execution. 
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By default, when you use the qualifiers discussed in this section, the debugger 
breaks or traces within all called routines as well as within the currently 
executing routine (this is equivalent to specifying SET BREAK/INTO or SET 
TRACE/INTO). By specifying SET BREAK/OVER or SET TRACE/OVER, you 
can suppress break or trace action within all called routines. Or, you can use 
the /[NOJJSB, /[NOJSHARE, or /[NOJSYSTEM qualifiers to specify the kinds of 
called routines where break or trace action is to be suppressed. For example, the 
next command causes the debugger to break on every line except within called 
routines that are in shareable images or system space: 

DBG> SET BREAK/LINE/NOSHARE/NOSYSTEM 

7.3.3 Controlling Debugger Action at Breakpoints or Tracepoints 

The SET BREAK and SET TRACE commands provide several options for 
controlling the behavior of the debugger at breakpoints and tracepoints—the 
/AFTER, /[NOJSILENT, /[NO]SOURCE, and /TEMPORARY command qualifiers, 
and the optional WHEN and DO clauses. The following examples show several of 
these options. 

The following command sets a breakpoint on line 14 and specifies that the 
breakpoint take effect after the fifth time that line 14 is executed: 

DBG> SET BREAK/AFTER:5 %LINE 14 

The following command sets a tracepoint that is triggered at every line of 

execution. The DO clause obtains the value of the variable X when each line is 
executed: 

DBG> SET TRACE/LINE DO (EXAMINE X) 

The following example shows how you capture the WHEN and DO clauses 
together. The command sets a breakpoint at line 27. The breakpoint is triggered 
(execution is paused) only when the value of SUM is greater than 100 (not each 
time line 27 is executed). The DO clause causes the value of TEST_RESULT to 
be examined whenever the breakpoint is triggered—that is, whenever the value 
of SUM is greater than 100. If the value of SUM is not greater than 100 when 
execution reaches line 27, the breakpoint is not triggered and the DO clause is 
not executed. 

DBG> SET BREAK ILINE 27 WHEN (SUM > 100) DO (EXAMINE TEST RESULT) 

See Section 8.1.5 and Section 13.3.2.2 for information about evaluating language 
expressions like SUM > 100. 

The /SILENT qualifier suppresses the break or trace message and source code 
display. This is useful when, for example, you want to use the SET TRACE 
command only to execute a debugger command at the tracepoint. In the following 
example, the SET TRACE command is used to examine the value of the Boolean 
variable STATUS at the tracepoint: 

DBG> SET TRACE/SILENT %LINE 83 DO (EXAMINE STATUS) 

DBG> GO 


SCREEN_IO\CLEAR\STATUS: OFF 
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In the next example, the SET TRACE command is used to count the number 
of times line 12 is executed. The first DEFINE/VALUE command defines a 
symbol COUNT and initializes its value to 0. The DO clause of the SET TRACE 
command causes the value of COUNT to be incremented and evaluated whenever 
the tracepoint is triggered (whenever execution reaches line 12). 

DBG> DEFINE/VALOE COUNT=0 

DBG> SET TRACE/SILENT %LINE 12 DO (DEF/VAL C0UNT=C0UNT+1;EVAL COUNT) 

Source lines are displayed by default at breakpoints, tracepoints, and watchpoints 
if they are available for the module being debugged. You can also control their 
display with the SET STEP [NOISOURCE command and the /[NO]SOURCE 
qualifier of the SET BREAK, SET TRACE, and SET WATCH commands. See 
Chapter 10 for information about how to control the display of source code in 
general and in particular at breakpoints, tracepoints, and watchpoints. 

7.3.4 Setting Breakpoints or Tracepoints on Exceptions 

The SET BREAK/EXCEPTION and SET TRACE/EXCEPTION commands direct 
the debugger to treat any exception generated by your program as a breakpoint 
or tracepoint, respectively. The breakpoint or tracepoint occurs before any 
application-declared exception handler is invoked. See Section 13.5 for debugging 
techniques associated with exceptions and condition handlers. 

7.3.5 Setting Breakpoints or Tracepoints on Events 

The SET BREAK and SET TRACE commands each have an fEVENT=event-name 
qualifier. You can use this qualifier to set breakpoints or tracepoints that are 
triggered by various events (denoted by event-name keywords). Events and their 
keywords are currently defined for the following event facilities: 

• ADA event facility, which defines DEC Ada tasking events. Ada events are 
defined in Section 16.6.4. 

• THREADS event facility, which defines tasking (multithread) events for 
programs written in any language that uses DECthreads services. Threads 
events are defined in Section 16.6.4. 

• SCAN event facility, which defines SCAN pattern-matching events. 

SCAN events are defined in the debugger’s online help (type 
HELP Language SCAN). ♦ 

The appropriate facility and event-name keywords are defined when the program 
is brought under debugger control. Use the SHOW EVENT_FACILITY command 
to identify the current event facility and the associated event-name keywords. 

The SET EVENT_FACILITY command enables you to change the event facility 
and change your debugging context. This is useful if you have a multilanguage 
program and want to debug a routine that is associated with an event facility but 
that facility is not currently set. 

For complete information about DECthreads and Ada events, including predefined 
event breakpoints, see Section 16.6.4. 

The following example shows how to set a SCAN event breakpoint. It causes the 
debugger to break whenever a SCAN token is built, for any value: 

DBG> SET BREAK/EVENT=TOKEN 

When a breakpoint or tracepoint is triggered, the debugger identifies the event 
that caused it to be triggered and gives additional information. 
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7.3.6 Deactivating, Activating, and Canceling Breakpoints or Tracepoints 

After a breakpoint or tracepoint is set, you can deactivate it, activate it, or cancel 


To deactivate a breakpoint or tracepoint, enter the DEACTIVATE BREAK 
or DEACTIVATE TRACE command. This causes the debugger to ignore the 
breakpoint or tracepoint during program execution. However, you can activate it 
at a later time, for example, when you rerun the program (see Section 5.3.3). A 
deactivated breakpoint or tracepoint is listed as such in a SHOW BREAK display. 

To activate a breakpoint or tracepoint, use the ACTIVATE BREAK or 
ACTIVATE TRACE command. Activating a breakpoint or tracepoint causes 
it to take effect during program execution. 

The commands DEACTIVATE BREAK/ALL and ACTIVATE BREAK/ALL 
(or DEACTIVATE TRACE/ALL and ACTIVATE TRACE/ALL) operate on all 
breakpoints or tracepoints and are particularly useful when rerunning a program 
with the RERUN command. 


To cancel a breakpoint or tracepoint, use the CANCEL BREAK or 
CANCEL TRACE command. A canceled breakpoint or tracepoint is no longer 
listed in a SHOW BREAK or SHOW TRACE display. 

When using any of these commands, specify the address expression and qualifiers 
(if any) exactly as you did when setting the breakpoint or tracepoint. For 
example: 


DBG> DEACTIVATE TRACE/LINE 

DBG> CANCEL BREAK SWAP,MOD2\LOOP4,2753 


7.4 Monitoring Changes in Variables and Other Program Locations 

The SET WATCH command enables you to specify program variables (or arbitrary 
memory locations) that the debugger monitors as your program executes. This 
process is called setting watchpoints. If, during execution, the program modifies 
the value of a watched variable (or memory location), the watchpoint is triggered. 
The debugger then suspends execution, displays information, and prompts 
for more commands. The debugger monitors watchpoints continuously during 
program execution. 

This section describes the general use of the SET WATCH command. Section 7.4.3 
gives additional information about setting watchpoints on nonstatic variables— 
variables that are allocated on the call stack or in registers. 


-- Note ___ 

In some cases, when using the SET WATCH command with a variable 
name (or any other symbolic address expression), you might need to set a 
module or specify a scope or a path name. Those concepts are described 
in Chapter 9. The examples in this section assume that all modules are 
set and that all variable names are uniquely defined. 

If your program was optimized during compilation, certain variables in 
the program might be removed by the compiler. If you then try to set 
a watchpoint on such a variable, the debugger issues a warning (see 
Section 5.2 and Section 13.1). 
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The syntax of the SET WATCH command is as follows: 

SET \NAlCH[/qualifier[ ... ]] address-expression[, ... ] 

[WHEN ( conditional-expression )] 

[DO {command^ ...])] 

You can specify any valid address expression, but usually you specify the 
name of a variable. The following example shows a typical use of the SET 
WATCH command and shows the general default behavior of the debugger at a 
watchpoint: 

DBG> SET WATCH COUNT 
DBG> GO 


watch of M0D2\C0UNT at M0D2\%LINE 24 
24: COUNT := COUNT + 1; 

old value: 27 
new value: 28 
break at M0D2\%LINE 25 
25: END; 

DBG> 

In this example, the SET WATCH command sets a watchpoint on the variable 
COUNT, and the GO command starts execution. When the program changes the 
value of COUNT, execution is paused. The debugger then does the following: 

• Announces the event ("watch of MOD2\COUNT . . . "), identifying the 
location of the instruction that changed the value of the watched variable 
(- .. . at MOD2\%LINE 24") 

• Displays the associated source line (24) 

• Displays the old and new values of the variable (27 and 28) 

• Announces that execution is paused at the beginning of the next line ("break 
at MOD2\%LINE 25") and displays that source line 

• Prompts for another command 

When the address of the instruction that modified a watched variable is not at 
the beginning of a source line, the debugger denotes the instruction’s location by 
displaying the line number plus the byte offset from the beginning of the line. 
For example: 

DBG> SET WATCH K 
DBG> GO 


watch of TEST\K at TEST\%LINE 19+5 
19: DO 40 K - 1, J 

old value: 4 
new value: 5 

break at TEST\%LINE 19+9 
19: DO 40 K = 1, J 

DBG> 

In this example, the address of the instruction that modified variable K is 5 bytes 
beyond the beginning of line 19. The breakpoint is on the instruction that follows 
the instruction that modified the variable (not on the beginning of the next source 
line as in the preceding example). 
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You can set watchpoints on aggregates (that is, entire arrays or records). A 
watchpoint set on an array or record triggers if any element of the array or record 
changes. Thus, you do not need to set watchpoints on individual array elements 
or record components. However, you cannot set an aggregate watchpoint on a 
variant record. In the following example, the watchpoint is triggered because 
element 3 of array ARR was modified: 

DBG> SET WATCH ARR 
DBG> GO 


watch of SUBR\ARR at SUBRULINE 12 
12: ARR(3) := 28 

old value: 


(1) 

7 

(2) 

12 

(3) 

3 

(4) 

0 

new value: 

(i) 

7 

(2) 

12 

(3) 

28 

(4) 

0 


break at SUBR\%LINE 13 
DBG> 

You can also set a watchpoint on a record component, on an individual array 
element, or on an array slice (a range of array elements). A watchpoint set on an 
array slice triggers if any element within that slice changes. When setting the 
watchpoint, use the syntax of the current language. For example, the following 
command sets a watchpoint on element 7 of array CHECK using Pascal syntax: 

DBG> SET WATCH CHECK[7] 

To identify all of the watchpoints that are currently set, use the SHOW WATCH 
command. 

7.4.1 Deactivating, Activating, and Canceling Watchpoints 

After a watchpoint is set, you can deactivate it, activate it, or cancel it. 

To deactivate a watchpoint, use the DEACTIVATE WATCH command. This 
causes the debugger to ignore the watchpoint during program execution. 
However, you can activate it at a later time, for example, when you rerun 
the program (see Section 5.3.3). A deactivated watchpoint is listed as such in a 
SHOW WATCH display. 

To activate a watchpoint, use the ACTIVATE WATCH command. Activating a 
watchpoint causes it to take effect during program execution. You can always 
activate a static watchpoint, but the debugger cancels a nonstatic watchpoint 
if execution moves out of the scope in which the variable is defined (see 
Section 7.4.3). 

The commands DEACTIVATE WATCH/ALL and ACTIVATE WATCH/ALL operate 
on all watchpoints and are particularly useful when rerunning a program with 
the RERUN command. 

To cancel a watchpoint, use the CANCEL WATCH command. A canceled 
watchpoint is no longer listed in a SHOW WATCH display. 
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Note that the SET BREAK/MODIFY and SET WATCH commands have the same 
effect. 

7.4.2 Watchpoint Options 

The SET WATCH command provides the same options for controlling the behavior 
of the debugger at watchpoints that the SET BREAK and SET TRACE commands 
provide for breakpoints and tracepoints—namely the /AFTER, /[NOJSILENT, 
/[NOISOURCE, and /TEMPORARY qualifiers, and the optional WHEN and DO 
clauses. See Section 7.3.3 for examples. 

7.4.3 Watching Nonstatic Variables 

____Note--- 

The generic term nonstatic variable is used here to denote what is 
called an automatic variable in some languages. 


Storage for a variable in your program is allocated either statically or 
nonstatically. A static variable is associated with the same memory address 
throughout execution of the program. A nonstatic variable is allocated on the 
call stack or in a register and has a value only when its defining routine is 
active on the call stack. As explained in this section, the technique for setting a 
watchpoint, the watchpoint’s behavior, and the speed of program execution are 
different for the two kinds of variables. 

To determine how a variable is allocated, use the EVALUATE/ADDRESS 
command. A static variable generally has its address in PO space (0 to 
3FFFFFFF, hexadecimal). A nonstatic variable generally has its address in 
PI space (40000000 to 7FFFFFFF, hexadecimal) or is in a register. In the 
following Pascal code example, X is declared as a static variable, but Y is a 
nonstatic variable (by default). The EVALUATE/ADDRESS command, entered 
while debugging, shows that X is allocated at memory location 512, but Y is 
allocated in register R0. 


VAR 

X: [STATIC] INTEGER; 
Y: INTEGER; 


DBG> EVALUATE/ADDRESS X 
512 

DBG> EVALUATE/ADDRESS Y 

%R0 

DBG> 

When using the SET WATCH command, note the following distinction. You can 
set a watchpoint on a static variable throughout execution of your program, but 
you can set a watchpoint on a nonstatic variable only when execution is paused 
within the scope of the variable’s defining routine. Otherwise, the debugger 
issues a warning. For example: 
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DBG> SET WATCH Y 

^DEBUG-W-SYMNOTACT, nonstatic variable 'MOD4\ROUT3\Y' 
is not active 

DBG> 

Section 7.4.3.2 describes how to set a watchpoint on a nonstatic variable. 

7.4.3.1 Execution Speed 

When a watchpoint is set, the speed of program execution depends on whether 
the variable is static or nonstatic. To watch a static variable, the debugger write- 
protects the page containing the variable. If your program attempts to write to 
that page (modify the value of that variable), an access violation occurs and the 
debugger handles the exception. The debugger temporarily unprotects the page 
to allow the instruction to complete and then determines whether the watched 
variable was modified. Except when writing to that page, the program executes 
at full speed. 

Because problems arise if the call stack or registers are write-protected, the 
debugger must use another technique to watch a nonstatic variable. It traces 
every instruction in the variable’s defining routine and checks the value of the 
variable after each instruction has been executed. Because this significantly slows 
down the execution of the program, the debugger issues the following message 
when you set a nonstatic watchpoint: 

DBG> SET WATCH Y 

-sDEBUG-I-WPTTRACE, nonstatic watchpoint, tracing every instruction 
DBG> 

7.4.3.2 Setting a Watchpoint on a Nonstatic Variable 

To set a watchpoint on a nonstatic variable, make sure that execution is paused 
within the defining routine. A convenient technique is to set a tracepoint on the 
routine that includes a DO clause to set the watchpoint. Thus, whenever the 
routine is called, the tracepoint is triggered and the watchpoint is automatically 
set on the local variable. In the following example, the WPTTRACE message 

indicates that a watchpoint has been set on Y, a nonstatic variable that is local to 
routine ROUT3: 

DBG> SET TRACE/NOSOURCE R00T3 DO (SET WATCH Y) 

DBG> GO 


trace at routine MOD4\ROOT3 

%DEBUG-I-WPTTRACE, nonstatic watchpoint, tracing every instruction 


watch of MOD4\ROUT3\Y at MOD4\ROUT3\%LINE 16 
16: Y := 4 

old value: 3 

new value: 4 

break at MOD4\ROUT3\%LINE 17 
17: SWAP(X,Y); 

DBG> 

When execution returns to the caller of routine ROUT3, variable Y is no longer 

fu* 1 ! 6 , - , Therefore ’ the debugger automatically cancels the watchpoint and issues 
the following messages: 


%DEBUG-I-WATCHVAR, watched variable MOD4\ROUT3\Y has 
%DEBUG-I-WATCHCAN, watchpoint now canceled 


gone out of scope 
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7.4.3.3 


Options for Watching Nonstatic Variables 

The SET WATCH command qualifiers /OVER, /INTO, and /[NOISTATIC provide 
options for watching nonstatic variables. 


When you set a watchpoint on a nonstatic variable, you can direct the debugger 
to do one of two things at a routine call: 


• Step over the called routine-executing it at full speed-and resume 
instruction tracing after returning. This is the default (SET WATCH/OVER). 

• Trace instructions within the called routine, which monitors the variable 
instruction-by-instruction within the routine (SET WATCH/INTO). 

Using the SET WATCH/OVER command results in better performance. However, 
if the called routine modifies the watched variable, the watchpoint is triggered 
only after execution returns from that routine. The SET WATCH/INTO command 
slows down program execution but enables you to monitor watchpoints more 
precisely within called routines. 


The debugger determines whether a variable is static or nonstatic by looking 
at its address (PO space, PI space, or register). When entering a SET WATCH 
command, you can override this decision with the /[NOISTATIC qualifier. For 
example, if you have allocated nonstack storage in PI space, use the SET WATCH 
/STATIC command to specify that a particular variable is static even though it 
is in PI space. Conversely, if you have allocated your own call stack in PO space, 
use the SET WATCH/NOSTATIC command to specify that a particular variable is 
nonstatic even though it is in PO space. 


7.4.3.4 Setting Watchpoints in Installed Writable Shareable Images 

When setting a watchpoint in an installed writable shareable image, use the SET 
WATCH/NOSTATIC command (see Section 7.4.3.3). 

The reason you must set a nonstatic watchpoint is as follows. Variables declared 
in such shareable images are typically static variables. By default, the debugger 
watches a static variable by write-protecting the page containing that variable. 
However, the debugger cannot write-protect a page in an installed writable 
shareable image. Therefore, the debugger must use the slower method of 
detecting changes, as for nonstatic variables—that is, by checking the value at the 
watched location after each instruction has been executed (see Section 7.4.3.1). 


If any other process modifies the watched location s value, the debugger may 
report that your program modified the watched location. 
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___ 8 

Examining and Manipulating Program Data 


This chapter explains how to use the EXAMINE and DEPOSIT commands to 
display and modify the values of symbols declared in your program as well as the 
of arbitrary program locations. The chapter also explains how to use the 
EVALUATE and other commands that evaluate language expressions. 

The topics covered in this chapter are organized as follows: 

• General concepts related to using the EXAMINE, DEPOSIT, and EVALUATE 
commands. 

Use of the commands with symbolic names—for example, the names of 
variables and routines declared in your program. Such symbolic address 
expressions are associated with compiler generated types. 

• Use of the commands with program locations (memory addresses or registers) 
that do not have symbolic names. Such address expressions are not 
associated with compiler generated types. 

• Specifying a type to override the type associated with an address expression. 

The examples in this chapter do not cover all language-dependent behavior. 

When debugging in any language, be sure also to consult the following 
documentation: 

Section 13.3, which highlights some important differences between languages 
that you should be aware of when debugging multilanguage programs. 

• The debugger’s online help (type HELP Language). 

The documentation supplied with that language. 

8.1 General Concepts 

This section introduces the EXAMINE, DEPOSIT, and EVALUATE commands 
and discusses concepts that are common to those commands. 

8.1.1 Accessing Variables While Debugging 

—--—- Note__ 

The generic term nonstatic variable is used here to denote what is 
called an automatic variable in some languages. 


Before you try to examine or deposit into a nonstatic (stack-local or register) 
variable, its defining routine must be active on the call stack. That is, 
program execution must be paused somewhere within the defining routine. 
See Section 7.4.3 for more information about nonstatic variables. 
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You can examine a static variable at any time during program execution, and 
you can examine a nonstatic variable as soon as execution reaches its defining 
routine. However, before you examine any variable, you should execute the 
program beyond the point where the variable is declared and initialized. The 
value contained in any uninitialized variable should be considered invalid. 

Many compilers optimize code to make the program run faster. If the code that 
you are debugging has been optimized, some program locations might not match 
what you would expect from looking at the source code. In particular, some 
optimization techniques eliminate certain variables so that you no longer have 
access to them while debugging. 

Section 13.1 explains the effect of several optimization techniques on the 
executable code. When first debugging a program, it is best to disable 
optimization, if possible, with the /NOOPTIMIZE (or equivalent) compiler 
command qualifier. 

In some cases, when using the EXAMINE or DEPOSIT command with a variable 
name (or any other symbolic address expression) you might need to set a module 
or specify a scope or a path name. Those concepts are described in Chapter 9. 

The examples in this chapter assume that all modules are set and that all 
variable names are uniquely defined. 

8.1.2 Using the EXAMINE Command 

For high-level language programs, the EXAMINE command is used mostly to 
display the current value of variables, and it has the following syntax: 

EXAMINE variable-name[, ... ] 

For example, the following command displays the current value of the integer 
variable X: 

DBG> EXAMINE X 
M0D3\X: 17 

DBG> 

When displaying the value, the debugger prefixes the variable name with its path 
name —in this case, the name of the module where variable X is declared (see 

Section 9.3.2). 

The EXAMINE command usually displays the current value of the entity, denoted 
by an address expression, in the type associated with that location (for example, 
integer, real, array, record, and so on). The basic syntax of the EXAMI 
command is as follows: 

EXAMINE address-expression[, . . . ] 

When you enter an EXAMINE command, the debugger evaluates the address 
expression to yield a program location (a memory address or a register). The 
debugger then displays the value stored at that location as follows: 

• If the location has a symbolic name, the debugger formats the value according 
to the compiler-generated type associated with that symbol. 

• If the location does not have a symbolic name, the debugger formats the value 
in the type longword integer by default. 

See Section 8.1.4 for more information about the types associated with symbolic 
and nonsymbolic address expressions. 


8-2 




Examining and Manipulating Program Data 

8.1 General Concepts 


By default, when displaying the value, the debugger identifies the address 
expression and its path name symbolically if symbol information is available. See 
Section 8.1.10 for more information about symbolizing addresses. 

8.1.3 Using the DEPOSIT Command 

For high-level languages, the DEPOSIT command is used mostly to assign a 
new value to a variable. The command is like an assignment statement in most 
programming languages, and it has the following syntax: 

DEPOSIT variable-name = value 

For example, the following DEPOSIT command assigns the value 23 to the 
integer variable X: 

DBG> EXAMINE X 
M0D3\X: 17 

DBG> DEPOSIT X = 23 
DBG> EXAMINE X 
M0D3\X: 23 

DBG> 

The DEPOSIT command usually evaluates a language expression and deposits 
the resulting value into a program location denoted by an address expression. 

The basic syntax of the DEPOSIT command is as follows: 

DEPOSIT address-expression = language-expression 

When you enter a DEPOSIT command, the debugger does the following: 

• It evaluates the address expression to yield a program location. 

• If the program location has a symbolic name, the debugger associates the 
location with the symbol’s compiler generated type. If the location does not 
have a symbolic name, the debugger associates the location with the type 
longword integer by default (see Section 8.1.4). 

• It evaluates the language expression in the syntax of the current language 
and in the current radix to yield a value. This behavior is identical to that of 
the EVALUATE command (see Section 8.1.5). 

• It checks that the value and type of the language expression is consistent 
with the type of the address expression. If you try to deposit a value that 
is incompatible with the type of the address expression, the debugger issues 
a diagnostic message. If the value is compatible, the debugger deposits the 
value into the location denoted by the address expression. 

Note that the debugger might do type conversion during a deposit operation if 
the language rules allow it. For example, assume X is an integer variable. In the 
following example, the real value 2.0 is converted to the integer value 2, which is 
then assigned to X: 

DBG> DEPOSIT X = 2.0 
DBG> EXAMINE X 
M0D3\X: 2 

DBG> 

In general, the debugger tries to follow the assignment rules for the current 
language. 
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8.1.4 Address Expressions and Their Associated Types 

The symbols that are declared in your program (variable names, routine names, 
and so on) are symbolic address expressions. They denote memory addresses 
or registers. Symbolic address expressions (also called symbolic names in this 
chapter) have compiler-generated types, and the debugger knows the type and 
location that are associated with symbolic names. Section 8.1.10 explains how to 
obtain memory addresses and register names from symbolic names and how to 
symbolize program locations. 

Symbolic names include the following categories: 

• Variables 

The associated program locations contain the current values of variables. 
Techniques for examining and depositing into variables are described in 
Section 8.2. 

• Routines, labels, and line numbers 

The associated program locations contain instructions. Techniques for 
examining and depositing instructions are described in Section 8.3. 

Program locations that do not have a symbolic name are not associated with 
a compiler-generated type. To enable you to examine and deposit into such 
locations, the debugger associates them with the default type longword integer. 

If you specify a location that does not have a symbolic name, the EXAMINE 
command displays the contents of four bytes starting at the address specified and 
formats the displayed information as an integer value. In the following example, 
the memory address 926 is not associated with a symbolic name (note that the 
address is not symbolized when the EXAMINE command is executed). Therefore, 
the EXAMINE command displays the value at that address as a longword integer: 

DBG> EXAMINE 926 
926: 749404624 

DBG> 

By default you can deposit up to four bytes of integer data into a program location 
that does not have a symbolic name. This data is formatted as a longword integer. 
For example: 

DBG> DEPOSIT 926 = 84 
DBG> EXAMINE 926 
926: 84 

DBG> 

Techniques for examining and depositing into locations that do not have a 
symbolic name are described in Section 8.5. 

The EXAMINE and DEPOSIT commands accept type qualifiers (/ASCII :n, 
/BYTE, and so on) that enable you to override the type associated with a 
program location. This is useful if you want the contents of the location to 
be interpreted and displayed in another type, or if you want to deposit some 
value of a particular type into a location that is associated with another type. 
Techniques for overriding a type are described in Section 8.5. 
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8.1.5 Evaluating Language Expressions 

A language expression consists of any combination of one or more symbols, 
literals, and operators that is evaluated to a single value in the syntax of the 
current language and in the current radix. (The current language and current 
radix are defined in Section 8.1.8 and Section 8.1.9, respectively.) Several 
debugger commands and constructs evaluate language expressions: 

• The EVALUATE and DEPOSIT commands, which are described in this 
section and in Section 8.1.3, respectively. 

• The IF, FOR, REPEAT, and WHILE commands (see Section 12.6). 

• WHEN clauses, which are used with the SET BREAK, SET TRACE, and SET 
WATCH commands (see Section 7.3.3). 

This discussion applies to all commands and constructs that evaluate language 
expressions, but it focuses on using the EVALUATE command. 

The EVALUATE command evaluates one or more language expressions in the 
syntax of the current language and in the current radix and displays the resulting 
values. The command has the following syntax: 

EVALUATE language-expression[, ... ] 

One use of the EVALUATE command is to perform arithmetic calculations that 
might be unrelated to your program. For example: 

DBG> EVALUATE (8+12)*6/4 
30 

DBG> 

The debugger uses the rules of operator precedence of the current language when 
evaluating language expressions. 

You can also evaluate language expressions that include variables and other 
constructs. For example, the following EVALUATE command subtracts 3 from 
the current value of the integer variable X, multiplies the result by 4, and 
displays the resulting value: 

DBG> DEPOSIT X = 23 
DBG> EVALUATE (X - 3) * 4 
80 

DBG> 

However, you cannot evaluate a language expression that includes a function call. 
For example, if PRODUCT is a function that multiplies two integers, you cannot 
enter the EVALUATE PRODUCT(3,5) command. If your program assigns the 
returned value of a function to a variable, you can examine the resulting value of 
that variable. 

If an expression contains symbols with different compiler generated types, the 
debugger uses the type-conversion rules of the current language to evaluate 
the expression. If the types are incompatible, a diagnostic message is issued. 
Debugger support for operators and other constructs in language expressions is 
listed in the debugger’s online help for each language (type HELP Language). 

The built-in symbol %CURVAL denotes the current value —the value last 
displayed by an EVALUATE or EXAMINE command or deposited by a DEPOSIT 
command. The backslash (\ ) also denotes the current value when used in that 
context. For example: 
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DBG> EXAMINE X 
M0D3\X: 23 

DBG> EVALUATE %CURVAL 
23 

DBG> DEPOSIT Y = 47 
DBG> EVALUATE \ 

47 

DBG> 

8.1.5.1 Using Variables in Language Expressions 

You can use variables in language expressions in much the same way that you 
use them in the source code of your program. 

Thus, the debugger generally interprets a variable used in a language expression 
as the current value of that variable, not the address of the variable. For example 
(X is an integer variable): 


DBG> DEPOSIT X = 12 
DBG> EXAMINE X 
M0D4\X: 12 

DBG> EVALUATE X 
12 

DBG> EVALUATE X + 4 
16 

DBG> DEPOSIT X = X/2 

DBG> EXAMINE X 
M0D4\X: 6 

DBG> 


! Assign the value 12 to X 
! Display the value of X 

! Evaluate and display the value of X 

! Add the value of X to 4 

! Divide the value of X by 2 and assign 
! the resulting value to X 
! Display the new value of X 


Using a variable in a language expression as shown in the previous examples 
is generally limited to single-valued, noncomposite variables. Typically, you can 
specify a multivalued, composite variable (like an array or record) in a language 
expression only if the syntax indicates that you are referencing only a single 
value (a single element of the aggregate). For example, if ARR is the name of an 
array of integers, the following command is invalid: 

DBG> EVALUATE ARR 

%DEBUG-W-NOVALUE , reference does not have a value 
DBG> 


However, the following commands are valid because only a single element of the 
array is referenced: 

DBG> EVALUATE ARR(2) ! Evaluate element 2 of array ARR 

37 

DBG> DEPOSIT K = 5 + ARR(2) ! Deposit the sum of two integer 
DBG> ! values into an integer variable 

If the current language is BLISS, the debugger interprets a variable in a language 
expression as the address of that variable. To denote the value stored in a 
variable, you must use the contents-of operator (period (.)). For example, when 
the language is set to BLISS: 
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DBG> EXAMINE Y 

M0D4\Y: 3 

! Display the value-of Y. 

DBG> EVALUATE Y 

02475B 

! Display the address of Y. 

DBG> EVALUATE .Y 

7 

! Display the value of Y. 

DBG> EVALUATE Y + 4 

! Add 4 to the address of Y and 

02475F 

! display the resulting value. 

DBG> EVALUATE .Y + 4 

! Add 4 to the value of Y and display 

7 

! the resulting value. 


DBG> 

For all languages, to obtain the address of a variable, use the 
EVALUATE/ADDRESS command as described in Section 8.1.10. The EVALUATE 
and EVALUATE/ADDRESS commands both display the address of an address 
expression when the language is set to BLISS. 

8.1.5.2 Numeric Type Conversion by the Debugger 

When evaluating language expressions involving numeric types of different 
precision, the debugger first converts lower-precision types to higher-precision 
types before performing the evaluation. In the following example, the debugger 
converts the integer 1 to the real 1.0 before doing the addition: 

DBG> EVALUATE 1.5+1 

2.5 

DBG> 

The basic rules are as follows: 

• If integer and real types are mixed, the integer type is converted to the real 
type. 

• If integer types of different sizes are mixed (for example, byte-integer and 
word-integer), the one with the smaller size is converted to the larger size. 

• If real types of different sizes are mixed (for example, G_float and H_float), 
the one with the smaller size is converted to the larger size. 

In general, the debugger allows more numeric type conversion than the 
programming language. In addition, the hardware type used for a debugger 
calculation (word, longword, G_float, and so on) might differ from that chosen by 
the compiler. Because the debugger is not as strongly typed or as precise as some 
languages, the evaluation of an expression by the EVALUATE command might 
differ from the result that would be calculated by compiler-generated code and 
obtained with the EXAMINE command. 

8.1.6 Address Expressions Compared to Language Expressions 

Do not confuse address expressions with language expressions. An address 
expression specifies a program location; a language expression specifies a value. 
In particular, the EXAMINE command expects an address expression as its 
parameter, and the EVALUATE command expects a language expression as its 
parameter. These points are shown in the next examples. 

In the following example, the value 12 is deposited into the variable X. This is 
confirmed by the EXAMINE command. The EVALUATE command computes and 
displays the sum of the current value of X and the integer literal 6: 
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DBG> DEPOSIT X = 12 
DBG> EXAMINE X 
M0D3\X: 12 
DBG> EVALUATE X + 6 
18 

DBG> 

In the next example, the EXAMINE command displays the value currently stored 
at the memory location that is 6 bytes beyond the address of X: 

DBG> EXAMINE X + 6 
MOD3\X+6: 274903 
DBG> 

In this case the location is not associated with a compiler-generated type. 
Therefore, the debugger interprets and displays the value stored at that location 
in the type longword integer (see Section 8.1.4). 

In the next example, the value of X + 6 (that is, 18) is deposited into the location 
that is 6 bytes beyond the address of X. This is confirmed by the last EXAMINE 
command. 

DBG> EXAMINE X 
MOD3\X: 12 

DBG> DEPOSIT X + 6 = X + 6 

DBG> EXAMINE X 

MOD3\X: 12 

DBG> EXAMINE X + 6 

MOD3\X+6: 18 

DBG> 

8.1.7 Specifying the Current, Previous, and Next Entity 

When using the EXAMINE and DEPOSIT commands, you can use three special 
built-in symbols (address expressions) to refer quickly to the current, previous, 
and next data locations (logical entities). These are the period (.), the circumflex 
( A ), and the Return key. 

The period (.), when used by itself with an EXAMINE or DEPOSIT command, 
denotes the current entity—that is, the program location most recently referenced 
by an EXAMINE or DEPOSIT command. For example: 

DBG> EXAMINE X 
SIZE\X: 7 

DBG> DEPOSIT . = 12 
DBG> EXAMINE . 

SIZE\X: 12 
DBG> 

The circumflex ( A ) and Return key denote, respectively, the previous and next 
logical data locations relative to the last EXAMINE or DEPOSIT command (the 
logical predecessor and successor, respectively). The circumflex and Return key 
are useful for referring to consecutive indexed components of an array. The 
following example shows the use of these operators with an array of integers, 
ARR: 
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DBG> EXAMINE 

ARR(5) 

! Examine 

MAIN\ARR(5): 

448670 


DBG> EXAMINE 

A 

! Examine 

MAIN\ARR(4): 

792802 


DBG> EXAMINE 

| Return | 

! Examine 

MAIN\ARR(5): 

448670 


DBG> EXAMINE 

| Return | 

! Examine 

MAIN\ARR(6): 
DBG> 

891236 



element 5 of array ARR 
the previous element (4) 
the next element (5) 
the next element (6) 


The debugger uses the type associated with the current entity to determine 
logical successors and predecessors. 

You can also use the built-in symbols %CURLOC, %PREVLOC, and %NEXTLOC 
to achieve the same purpose as the period, circumflex, and Return key, 
respectively. These symbols are useful in command procedures and also if 
your program uses the circumflex for other purposes. Moreover, using the Return 
key to signify the logical successor does not apply to all contexts. For example, 
you cannot press the Return key after entering the DEPOSIT command to 
indicate the next location, but you can always use the symbol %NEXTLOC for 
that purpose. 

Note that, like EXAMINE and DEPOSIT, the EVALUATE/ADDRESS command 
also resets the values of the current, previous, and next logical-entity built-in 
symbols (see Section 8.1.10). However, you cannot press the Return key after 
entering the EVALUATE/ADDRESS command to indicate the next location. For 
more information about debugger built-in symbols, see Appendix B. 

The previous examples show the use of the built-in symbols after referencing a 
symbolic name with the EXAMINE or DEPOSIT command. If you examine or 
deposit into a memory address, that location might or might not be associated 
with a compiler-generated type. When you reference a memory address, the 
debugger uses the following conventions to determine logical predecessors and 
successors: 

• If the address has a symbolic name (the name of a variable, component of 
a composite variable, routine, and so on), the debugger uses the associated 
compiler-generated type. 

• If the address does not have a symbolic name, the debugger uses the type 
longword integer by default. 

As the current entity is reset with new examine or deposit operations, the 
debugger associates each new location with a type in the manner indicated to 
determine logical successors and predecessors. This is shown in the following 
examples. 

Assume that a FORTRAN program has declared three variables, ARY, FLT, and 
BTE, as follows: 

• ARY is an array of three word integers (2 bytes each) 

• FLT is an F_floating type (4 bytes) 

• BTE is a byte integer (1 byte) 

Assume that storage for these variables has been allocated at consecutive 
addresses in memory, starting with 1000. For example: 


8-9 







Examining and Manipulating Program Data 
8.1 General Concepts 


1000: ARY(1) 
1002: ARY(2) 
1004: ARY(3) 
1006: FLT 
1010: BTE 
1011: undefined 


Examining successive logical data locations will give the following results: 


DBG> EXAMINE 1000 
MOD3\ARY(1): 13 

DBG> EXAMINE ptetwFl 
MOD3\ARY(2): 7 

DBG> EXAMINE [Riul^l 
MOD3\ARY(3) : 19 

DBG> EXAMINE [RetwRI 
MOD3\FLT: 1.9117807E+07 
DBG> EXAMINE [FtetUF^ 
MOD3\BTE: 43 

DBG> EXAMINE [RitUFFI 
1011: 17694732 
DBG> 


! Examine ARY (1), associated with 1000. 
! Current entity is now ARY( 1 ). 

! Examine next location, ARY(2), 

! using type of ARY(l) as reference. 

! Examine next location, ARY(3). 

! Current entity is now ARY(3). 

! Examine entity at 1006 (FLT). 

! Current entity is now FLT. 

! Examine entity at 1010 (BTE). 

! Current entity is now BTE. 

! Examine entity at 1011 (undefined). 

! Interpret data as longword integer. 

! Location is not symbolized. 


The same principles apply when you use type qualifiers with the EXAMINE 
and DEPOSIT commands (see Section 8.5.2). The type specified by the qualifier 
determines the data boundary of an entity and, therefore, any logical successors 
and predecessors. 


8.1.8 Language Dependencies and the Current Language 

The debugger enables you to set your debugging context to any of several 
supported languages. The setting of the current language determines how the 
debugger parses and interprets the names, numbers, operators, and expressions 
you specify in debugger commands, and how it displays data. 

By default, the current language is the language of the module containing the 
main program, and it is identified when you bring the program under debugger 
control. For example: 

$ PASCAL/NOOPTIMIZE/DEBOG TEST1 
$ LINK/DEBUG TEST1 
$ DEBUG/KEEP 

Debugger Banner and Version Number 
DBG> RUN TEST1 

%DEBUG-I-INITIAL, language is PASCAL, module set to TESTl 
DBG> 


When debugging modules whose code is written in other languages, you can use 
the SET LANGUAGE command to establish a new language-dependent context. 
Section 13.3 highlights some important language differences. Debugger support 
for operators and other constructs in language expressions is listed for each 
language in the debugger’s online help (type HELP Language). 

8.1.9 Specifying a Radix for Entering or Displaying Integer Data 

The debugger can interpret and display integer data in any one of four radixes: 
decimal, hexadecimal, octal, and binary. The default radix is decimal for most 
languages. 
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4^ 4 


Alpha 


On VAX processors, the exceptions are BLISS and MACRO-32, which have a 
default radix of hexadecimal. ♦ 

On Alpha processors, the exceptions are BLISS, MACRO-32 and MACRO-64, 
which have a default radix of hexadecimal. ♦ 

You can control the radix for the following kinds of integer data: 

• Data that you specify in address expressions or language expressions 

• Data that is displayed by the EVALUATE and EXAMINE commands 

You cannot control the radix for other kinds of integer data. For example, 
addresses are always displayed in hexadecimal radix in a SHOW CALLS display. 
Or, when specifying an integer n with various command qualifiers (/AFTER:ra, 
/UP :n, and so on) you must use decimal radix. 

The technique you use to control radix depends on your objective. To establish 
a new radix for all subsequent commands, use the SET RADIX command. For 
example: 

DBG> SET RADIX HEXADECIMAL 

After this command is executed, all integer data that you enter in address or 
language expressions is interpreted as being hexadecimal. Also, all integer data 
displayed by the EVALUATE and EXAMINE commands is given in hexadecimal 
radix. 

The SHOW RADIX command identifies the current radix (which is either the 
default radix, or the radix last established by a SET RADIX command). For 
example: 

DBG> SHOW RADIX 
input radix: hexadecimal 
output radix: hexadecimal 
DBG> 

The SHOW RADIX command identifies both the input radix (for data entry) 
and the output radix (for data display). The SET RADIX command qualifiers 
/INPUT and /OUTPUT enable you to specify different radixes for data entry 
and display. For more information, see the SET RADIX command description in 
online help. 

Use the CANCEL RADIX command to restore the default radix. 

The examples that follow show several techniques for displaying or entering 
integer data in another radix without changing the current radix. 

To convert some integer data to another radix without changing the current 
radix, use the EVALUATE command with a radix qualifier (/BINARY, /DECIMAL, 
/HEXADECIMAL, /OCTAL). For example: 

DBG> SHOW RADIX 
input radix: decimal 
output radix: decimal 
DBG> EVALUATE 18+5 
23 

DBG> EVALUATE/HEX 18+5 
00000017 
DBG> 

The radix qualifiers do not affect the radix for data entry. 


! 23 is decimal integer. 

! 17 is hexadecimal integer. 
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To display the current value of an integer variable (or the contents of a program 
location that has an integer type) in another radix, use the EXAMINE command 
with a radix qualifier. For example: 

DBG> EXAMINE X 

M0D4\X: 4398 ! 4398 is a decimal integer. 

DBG> EXAMINE/OCTAL . ! X is the current entity. 

M0D4\X: 00000010456 ! 10456 is an octal integer. 

DBG> 


To enter one or more integer literals in another radix without changing the 
current radix, use one of the radix built-in symbols %BIN, %DEC, %HEX, or 
%OCT. A radix built-in symbol directs the debugger to treat an integer literal 
that follows (or all numeric literals in a parenthesized expression that follows) as 
a binary, decimal, hexadecimal, or octal number, respectively. These symbols do 
not affect the radix for data display. For example: 


DBG> SHOW RADIX 
input radix: decimal 
output radix: decimal 
DBG> EVAL %BIN 10 
2 

DBG> EVAL %HEX (10 + 10) 
32 

DBG> EVAL %HEX 20+33 
65 

DBG> EVAL/HEX %OCT 4672 


! Evaluate the binary integer 10. 

! 2 is a decimal integer. 

! Evaluate the hexadecimal integer 20. 

! 32 is a decimal integer. 

! Treat 20 as hexadecimal, 33 as decimal. 
! 65 is a decimal integer. 

! Treat 4672 as octal and display in hex. 


000009BA ! 

DBG> EXAMINE X + %DEC 12 ! 

MOD3\X+12: 493847 ! 

DBG> DEPOS J = %OCT 7777777 ! 

DBG> EXAMINE . ! 

MOD3\J: 2097151 
DBG> EXAMINE/OCTAL . ! 

MOD3\J: 00007777777 
DBG> EXAMINE %HEX 0A34D ! 

SHARE$LIBRTL+4941: 344938193 ! 

DBG> 


9BA is a hexadecimal number. 

Examine the location 12 decimal bytes 
beyond the address of X. 

Deposit an octal value. 

Display that value in decimal radix. 

Display that value in octal radix. 

Examine location A34D, hexadecimal. 
344938193 is a decimal integer. 


__ Note ___ 

When specifying a hexadecimal integer that starts with a letter rather 
than a number (for example, A34D in the last example), add a leading 
0. Otherwise, the debugger tries to interpret the integer as a symbol 
declared in your program. 


For more examples showing the use of the radix built-in symbols, see Appendix B. 

8.1.10 Obtaining and Symbolizing Memory Addresses 

Use the EVALUATE/ADDRESS command to determine the memory address 
or the register name associated with a symbolic address expression, such as a 
variable name, line number, routine name, or label. For example: 

DBG> EVALUATE/ADDRESS X ! A variable name 

2476 

DBG> EVALUATE/ADDRESS SWAP ! A routine name 
1536 

DBG> EVALDATE/ADDRESS %LINE 26 

1629 

DBG> 
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The address is displayed in the current radix (as defined in Section 8.1.9). You 
can specify a radix qualifier to display the address in another radix. For example: 

DBG> EVALUATE/ADDRESS/HEX X 

000009AC 

DBG> 

If a variable is associated with a register instead of a memory address, the 
EVALUATE/ADDRESS command displays the name of the register, regardless of 
whether a radix qualifier is used. The following command indicates that variable 
K (a nonstatic variable) is associated with register R2: 

DBG> EVALUATE/ADDRESS K 

%R2 

DBG> 

Like the EXAMINE and DEPOSIT commands, EVALUATE/ADDRESS resets 
the values of the current, previous, and next logical-entity built-in symbols (see 
Section 8.1.7). Unlike the EVALUATE command, EVALUATE/ADDRESS does not 
affect the current-value built-in symbols %CURVAL and backslash (\ ). 

The SYMBOLIZE command does the reverse of EVALUATE/ADDRESS, but 
without affecting the current, previous, or next logical-entity built-in symbols. It 
converts a memory address or a register name into its symbolic representation 
(including its path name) if such a representation is possible (Chapter 9 explains 
how to control symbolization). For example, the following command shows that 
variable K is associated with register R2: 

DBG> SYMBOLIZE %R2 
address MOD3UR2: 

M0D3\K 

DBG> 

By default, symbolic mode is in effect (SET MODE SYMBOLIC). Therefore, the 
debugger displays all addresses symbolically if symbols are available for the 
addresses. For example, if you specify a numeric address with the EXAMINE 
command, the address is displayed in symbolic form if symbolic information is 
available: 

DBG> EVALUATE/ADDRESS X 
2476 

DBG> EXAMINE 2476 
M0D3\X: 16 

DBG> 

However, if you specify a register that is associated with a variable, the 
EXAMINE command does not convert the register name to the variable name. 
For example: 

DBG> EVALUATE/ADDRESS K 
%R2 

DBG> EXAMINE %R2 
MOD3UR2: 78 
DBG> 

By entering the SET MODE NOSYMBOLIC command, you disable symbolic mode 
and cause the debugger to display numeric addresses rather than their symbolic 
names. When symbolization is disabled, the debugger might process commands 
somewhat faster because it does not need to convert numbers to names. The 
EXAMINE command has a /[NOJSYMBOLIC qualifier that enables you to control 
symbolization for a single EXAMINE command. For example: 
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DBG> EVALUATE/ADDRESS Y 
512 

DBG> EXAMINE 512 
M0D3\Y: 28 

DBG> EXAMINE/NOSYMBOLIC 512 

512: 28 

DBG> 

Symbolic mode also affects the display of instructions. 

For example, on VAX processors: 

DBG> EXAMINE/INSTRUCTION .%PC 
M0D5\%LINE 14+2: MOVAL L A M0D4\X,R11 
DBG> EXAMINE/NOSYMBOL/INSTRUCTION .%PC 
1538: MOVAL L A 1080,R11 

DBG> ♦ 

8.2 Examining and Depositing into Variables 

The examples in this section show how to use the EXAMINE and DEPOSIT 
commands with variables. 

Languages differ in the types of variables they use, the names for these types, 
and the degree to which different types can be intermixed in expressions. The 
following generic types are discussed in this section: 

• Scalars (such as integer, real, character, or Boolean) 

• Strings 

• Arrays 

• Records 

• Pointers (access types) 

The most important consideration when examining and manipulating variables in 
high-level language programs is that the debugger recognizes the names, syntax, 
type constraints, and scoping rules of the variables in your program. Therefore, 
when specifying a variable with the EXAMINE or DEPOSIT command, you use 
the same syntax that is used in the source code. The debugger processes and 
displays the data accordingly. Similarly, when assigning a value to a variable, the 
debugger follows the typing rules of the language. It issues a diagnostic message 
if you try to deposit an incompatible value. The examples in this section show 
some of these invalid operations and the resulting diagnostics. 

When using the DEPOSIT command (or any other command), note the following 
behavior. If the debugger issues a diagnostic message with a severity level of I 
(informational), the command is still executed (the deposit is made in this case). 
The debugger aborts an illegal command line only when the severity level of the 
message is W (warning) or greater. 

For additional language-specific information, see the debugger’s online help (type 
HELP Language). 
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8.2.1 Scalar Types 

The following examples show use of the EXAMINE, DEPOSIT, and EVALUATE 
commands with some integer, real, and Boolean types. 

Examine a list of three integer variables: 

DBG> EXAMINE WIDTH, LENGTH, AREA 

SIZE\WIDTH: 4 

SIZE\LENGTH: 7 

SIZEYAREA: 28 

DBG> 

Deposit an integer expression: 

DBG> DEPOSIT WIDTH = CURRENT_WIDTH + 10 
DBG> 

The debugger checks that a value to be assigned is compatible with the data type 
and dimensional constraints of the variable. The following example shows an 
attempt to deposit an out-of-bounds value (X was declared as a positive integer): 

DBG> DEPOSIT X = -14 

%DEBUG-I-IVALOUTBNDS, value assigned is out of bounds at or near DEPOSIT 
DBG> 

If you try to mix numeric types (integer and real of varying precision) in a 
language expression, the debugger generally follows the rules of the language. 
Strongly typed languages do not allow much, if any, mixing. With some 
languages, you can deposit a real value into an integer variable. However, 
the real value is converted into an integer. For example: 

DBG> DEPOSIT I = 12345 

DBG> EXAMINE I 

M0D3\I: 12345 

DBG> DEPOSIT I = 123.45 

DBG> EXAMINE I 

M0D3\I: 123 

DBG> 

If numeric types are mixed in an expression, the debugger performs type 
conversion as discussed in Section 8.1.5.2. For example: 

DBG> DEPOSIT Y = 2.356 ! Y is of type D_floating point. 

DBG> EXAMINE Y 
MOD3\Y: 2.35600000000000 
DBG> EVALUATE Y + 3 
5.35600000000000 

DBG> DEPOSIT R = 5.35E3 ! R is of type F_floating point. 

DBG> EXAMINE R 
MOD3\R: 5350.000 
DBG> EVALUATE R*50 
267500.0 

DBG> DEPOSIT I = 22222 
DBG> EVALUATE R/I 
0.2407524 
DBG> 

The next example shows some operations with Boolean variables. The values 
TRUE and FALSE are assigned to the variables WILLING and ABLE, 
respectively. The EVALUATE command then obtains the logical conjunction 
of these values: 
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DBG> DEPOSIT WILLING = TRUE 
DBG> DEPOSIT ABLE = FALSE 
DBG> EVALUATE WILLING AND ABLE 
False 
DBG> 

8.2.2 ASCII String Types 

When displaying an ASCII string value, the debugger encloses it within quotation 
marks (") or apostrophes ('), depending on the language syntax. For example: 

DBG> EXAMINE EMPLOYEE_NAME 

PAYROLL\EMPLOYEE_NAME: "Peter C. Lombardi" 

DBG> 

To deposit a string value (including a single character) into a string variable, you 
must enclose the value in quotation marks (") or apostrophes ('). For example: 

DBG> DEPOSIT PART_NUMBER = "WG-7619.3-84" 

DBG> 

If the string has more ASCII characters (1 byte each) than can fit into the location 
denoted by the address expression, the debugger truncates the extra characters 
from the right and issues the following message: 

%DEBUG-I-ISTRTRU, string truncated at or near DEPOSIT 

If the string has fewer characters, the debugger pads the remaining characters to 
the right of the string by inserting ASCII space characters. 

8.2.3 Array Types 

You can examine an entire array aggregate, a single indexed element, or a slice 
(a range of elements). However, you can deposit into only one element at a time. 
The following examples show typical operations with arrays. 

The following command displays the values of all the elements of the array 
variable ARRX, a one-dimensional array of integers: 

DBG> EXAMINE ARRX 
MOD3\ARRX 


(1) 

42 

(2) 

17 

(3) 

278 

(4) 

56 

(5) 

113 

(6) 

149 


DBG> 

The following command displays the value of element 4 of array ARRX (depending 
on the language, parentheses or brackets are used to denote indexed elements): 

DBG> EXAMINE ARRX(4) 

MOD3\ARRX(4): 56 

DBG> 

The following command displays the values of all the elements in a slice of ARRX. 
This slice consists of the range of elements from element 2 to element 5: 

DBG> EXAMINE ARRX(2:5) 

MOD3\ARRX 


(2): 

17 

(3) : 

278 

(4) : 

56 

(5): 

113 


DBG> 
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In general, a range of values to be examined is denoted by two values separated 
by a colon (valuel:value2). Depending on the language, two periods (..) can be 
used instead of a colon. 

You can deposit a value to only a single array element at a time (you cannot 
deposit to an array slice or an entire array aggregate with a single DEPOSIT 
command). For example, the following command deposits the value 53 into 
element 2 of ARRX: 

DBG> DEPOSIT ARRX(2) = 53 
DBG> 

The following command displays the values of all the elements of array REAL. 
ARRAY, a two-dimensional array of real numbers (three per dimension): 

DBG> EXAMINE REAL_ARRAY 
PR0G2\REAL_ARRAY 

(1.1) : 27.01000 

(1.2) : 31.00000 

(1.3) : 12.48000 

(2.1) : 15.08000 

(2.2) : 22.30000 

(2.3) : 18.73000 

DBG> 

The debugger issues a diagnostic message if you try to deposit to an index value 
that is out of bounds. For example: 

DBG> DEPOSIT REAL_ARRAY(1,4) = 26.13 

%DEBUG-I-SUBOUTBND, subscript 2 is out of bounds, value is 4, 

bounds are 1..3 

DBG> 

In the previous example, the deposit operation was executed because the 
diagnostic message is of I level. This means that the value of some array element 
adjacent to (1,3), possibly (2,1) might have been affected by the out-of-bounds 
deposit operation. 

To deposit the same value to several components of an array, you can use a 
looping command such as FOR or REPEAT. For example, assign the value RED 
to elements 1 to 4 of the array COLOR_ARRAY: 

DBG> FOR I = 1 TO 4 DO (DEPOSIT COLOR ARRAY(I) = RED) 

DBG> 

You can also use the built-in symbols (.) and ( A ) to step through array elements, 
as explained in Section 8.1.7. 

8.2.4 Record Types 

- Note__ 

The generic term record is used here to denote a data structure whose 
elements have heterogeneous data types—what is called a struct type in 
the C language. 


You can examine an entire record aggregate, a single record component, or several 
components. However, you can deposit into only one component at a time. The 
following examples show typical operations with records. 
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The following command displays the values of all the components of the record 
variable PART: 

DBG> EXMINE PART 
INVENTORY\PART: 

ITEM: "WF-1247" 

PRICE: 49.95 

IN_ST0CK: 24 

DBG> 

The following command displays the value of component IN_STOCK of record 
PART (general syntax): 

DBG> EXMINE PART. IN_ST0CK 
INVENTORY\PART.IN_STOCK: 24 
DBG> 

The following command displays the value of the same record component using 
COBOL syntax (the language must be set to COBOL): 

DBG> EXMINE IN_STOCK OF PART 
INVENTORY\IN_STOCK of PART: 

IN_ST0CK: 24 

DBG> 

The following command displays the values of two components of record PART: 

DBG> EXMINE PART.ITEM, PART.IN_ST0CK 
INVENTORY\PART.ITEM: "WF-1247" 

INVENTORY\PART.IN_ST0CK: 24 

DBG> 

The following command deposits a value into record component IN_STOCK: 

DBG> DEPOSIT PART.IN_STOCK = 17 
DBG> 

8-2.5 Pointer (Access) Types 

You can examine the entity designated (pointed to) by a pointer variable and 
deposit a value into that entity. You can also examine a pointer variable. 

For example, the following Pascal code declares a pointer variable A that 
designates a value of type real: 


TYPE 

T = A REAL; 

VAR 

A : T; 


The following command displays the value of the entity designated by the pointer 
variable A: 

DBG> EXAMINE A A 
M0D3\A A : 1.7 
DBG> 
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In the following example, the value 3.9 is deposited into the entity designated by 
A: 

DBG> DEPOSIT A A = 3.9 
DBG> EXAMINE A A 
M0D3\A A : 3.9 
DBG> 

When you specify the name of a pointer variable with the EXAMINE command, 
the debugger displays the memory address of the object it designates. For 
example: 

DBG> EXAMINE/HEXADECIMAL A 

SAMPLEYA: 0000B2A4 

DBG> 


8.3 Examining and Depositing Instructions 

See Chapter 15 for additional information about vector instructions. 


The debugger recognizes address expressions that are associated with 
instructions. This enables you to examine and deposit instructions using the 
same basic techniques as with variables. 


When debugging at the instruction level, you might find it convenient to first 
enter the following command. It sets the default step mode to stepping by 
instruction: 

DBG> SET STEP INSTRUCTION 
DBG> 

There are other step modes that enable you to execute the program to specific 
kinds of instructions. You can also set breakpoints to interrupt execution at these 
instructions. 

In addition, you can use a screen-mode instruction display (see Section 11.2.4) to 
display the actual decoded instruction stream of your progr am 


8.3.1 Examining Instructions 

If you specify an address expression that is associated with an instruction in an 
EXAMINE command (for example, a line number), the debugger displays the 
first instruction at that location. You can then use the period (.), Return key, 
and circumflex ( A ) to display the current, next, and previous instruction (logical 
entity), as described in Section 8.1.7. 


Alpha 


For example, on Alpha processors: 


DBG> EXAMINE %LINE 

12 



M0D3ULINE 12: 

BIS 

R31,R31,R2 


DBG> EXAMINE [RifcPSl 
M0D3\%LINE 12+4: 

BIS 

R31,R2,R0 

! Next instruction. 

DBG> EXAMINE 1 Return | 
M0D3ULINE 12+8: 
DBG> EXAMINE A 

ADDL 

R31,R0,R0 

! Next instruction. 

M0D3ULINE 12+4: 

BIS 

R31,R2,R0 ! 

! Previous instruction. 


DBG> ♦ 


Line numbers, routine names, and labels are symbolic address expressions that 
are associated with instructions. In addition, instructions might be stored in 
various other memory addresses and in certain registers during the execution of 
your program. 
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4^4 


The program counter (PC) is the register that contains the address of the next 
instruction to be executed by your program. The command EXAMINE .%PC 
displays that instruction. The period (.), when used directly in front of an 
address expression, denotes the contents of operator—that is, the contents of the 
location designated by the address expression. Note the following distinction: 

• EXAMINE %PC displays the current PC value, namely the address of the 
next instruction to be executed. 

• EXAMINE ,%PC displays the contents of that address, namely the next 
instruction to be executed by the program. 

On VAX processors, you can use the /OPERANDS qualifier to control the amount 
of information displayed when you enter the EXAMINE .%PC command: 

DBG> EXAMINE .%PC 

M0D3\%LINE 12: MOVL B A 12(R11),R1 

DBG> EXAMINE/OPERANDS .%PC 

M0D3\%LINE 12: MOVL B A 12(R11),R1 

B A 12(Rll) M0D3\K (address 1196) contains 1 
R1 R1 contains 8 

DBG> EXAMINE/OPERANDS=FULL .%PC 
M0D3ULINE 12: MOVL B A 12(R11),R1 

B A 12(Rll) Rll contains M0D3\N (address 1184), B A 12(1184) evaluates to 
M0D3\K (address 1196), which contains 1 
R1 R1 contains 8 

DBG> 

Use the /OPERANDS qualifier only when examining the current PC instruction. 
The information might not be reliable if you specify other locations. The command 
SET MODE [NOJOPERANDS enables you to control the default behavior of the 
EXAMINE ,%PC command. ♦ 

As shown in the previous examples, the debugger knows whether an address 
expression is associated with an instruction. If it is, the EXAMINE command 
displays that instruction (you do not need to use the /INSTRUCTION 
qualifier). You use the /INSTRUCTION qualifier to display the contents of an 
arbitrary program location as an instruction—that is, the command EXAMINE 
/INSTRUCTION causes the debugger to interpret and format the contents of any 
program location as an instruction (see Section 8.5.2). 

When you examine consecutive instructions in a MACRO-32 program, the 
debugger might misinterpret data as instructions if storage for the data is 
allocated in the middle of a stream of instructions. The following example shows 
this problem. It shows some MACRO-32 code with two longwords of data storage 
allocated directly after the BRB instruction at line 7 (line numbers have been 
added to the example for clarity): 
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Table 8-1 (Cont.) Debugger Symbols for VAX Registers 


Symbol 

Description 

VAX General Registers 

%PC (%R15) 

Program counter (PC) 

%PSL 

Processor status longword (PSL) 

VAX Vector Registers and Vector Control Registers 

%V0 ... %V15 

Vector registers VO . . . V15 

%VCR 

Vector count register 

%VLR 

Vector length register 

%VMR 

Vector mask register 


On VAX processors: 

• You can omit the percent sign (%) prefix if your program has not declared a 
symbol with the same name. 

You can examine the contents of all the registers. You can deposit values into 
all the registers except for SP. Use caution when depositing values into FP. ♦ 

On Alpha processors, the Alpha architecture provides 32 general (integer) 
registers and 32 floating-point registers, some of which are used for temporary 
address and data storage. Table 8-2 identifies the debugger built-in symbols that 
refer to Alpha registers. 


Table 8-2 Debugger Symbols for Alpha Registers 
Symbol Description 


Alpha Integer Registers 


%R0 . . . %R28 

Registers R0 . . . R28 

%FP (%R29) 

Stack frame base register (FP) 

%SP (%R30) 

Stack pointer (SP) 

%R31 

ReadAsZero/Sink (RZ) 

%PC 

Program counter (PC) 

%PS 

Processor status register (PS). The built-in symbols %PSL and 
%PSW are disabled for Alpha processors. 

Alpha Floating-Point Registers 

%F0 . . . %F30 

Registers F0 . . . F30 

%F31 

ReadAsZero/Sink 


On Alpha processors: 

You can omit the percent sign (%) prefix if your program has not declared a 
symbol with the same name. 

• You cannot deposit a value into registers R31 or F31. They are permanently 
assigned the value 0. 

• There are no vector registers. 
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• The debugger does not provide a screen-mode register display. ♦ 

The following examples show how to examine and deposit into registers: 


DBG> SHOW TYPE 
type: long integer 
DBG> SHOW RADIX 
input radix: decimal 
output radix: decimal 
DBG> EXAMINE %R11 
M0D3\%R11: 1024 

DBG> DEPOSIT %R11 = 444 
DBG> EXAMINE %R11 
Rll: 444 
DBG> EXAMINE %PC 
MOD\%PC: 1553 
DBG> EXAMINE %SP 
0\%SP: 2147278720 


! Show type for locations without 
! a compiler-generated type. 

! identify current radix. 

! Display value in Rll. 

! Deposit new value into Rll. 

! Check new value. 

! Display value in program counter. 

! Display value in stack pointer. 


DBG> 


See Section 8.3.1 for specific information about the PC. 


8.4.1 Processor Status Longword (VAX Only) 

On VAX processors, the processor status longword (PSL) is a register whose value 
represents a number of processor state variables. The first 16 bits of the PSL 
(referred to separately as the processor status word, or PSW) contain unprivileged 
information about the current processor state. The values of these bits can be 
controlled by a user program. The latter 16 bits of the PSL, bits 16 to 31, contain 
privileged information and cannot be altered by a user-mode program. 

The following example shows how to examine the contents of the PSL: 

DBG> EXAMINE %PSL 
MOD3\PSL: 

CMP TP FPD IS CURMOD PRVMOD IPL DV FU IV T N Z V C 
n n n n mode mode lv n n nnnnnn 

DBG> 

See the VAX Architecture Handbook for complete information about the PSL, 
including the values of the various bits. 

You can also display the information in the PSL in other formats. For example: 

DBG> EXAMINE/LONG/HEX %PSL 
MOD3\%PSL: 03C00010 

DBG> EXAMINE/LONG/BIN %PSL 

MOD3\%PSL: 00000011 11000000 00000000 00010000 

DBG> 

The command EXAMINE/PSL displays the value at any location in PSL format. 
This is useful for examining saved PSLs on the call stack. 

To disable all conditions in the PSL, clear bits 0 to 15 with the following 
DEPOSIT command: 


DBG> DEPOSIT/WORD PSL = 0 
DBG> EXAMINE/PSL 
MOD3\PSL: 

CMP TP FPD IS CURMOD PRVMOD IPL DV FU IV T N Z V C 
0000 USER USER 0 00000000 

DBG> ♦ 
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8.4.2 Processor Status (Alpha Only) 


On Alpha processors, the processor status (PS) is a register whose value 
represents a number of processor state variables. The first three bits of the 
PS are reserved for the use of the software. The values of these bits can be 
controlled by a user program. The remainder of the bits, bits 4 to 64, contain 
privileged information and cannot be altered by a user-mode program. 

The following example shows how to examine the contents of the PS: 

DBG> EXAMINE %PS 
MODI\IPS: 

SP_ALIGN IPL VMM CM IP SW 
48 00 USER 0 3 



DBG> 


See the Alpha Architecture Reference Manual for complete information about the 
PS, including the values of the various bits. 

You can also display the information in the PS in other formats. For example: 

DBG> EXAMINE/LONG/HEX IPS 


MODI\IPS: 0000001B 

DBG> EXAMINE/LONG/BIN IPS 


M0D1\IPS: 

DBG> 


00000000 00000000 00000000 00011011 


The command EXAMINE/PS displays the value at any location in PS format. 
This is useful for examining the combined current and saved PS values. ♦ 


8.5 Specifying a Type When Examining and Depositing 


The preceding sections explain how to use the EXAMINE and DEPOSIT 
commands with program locations that have a symbolic name and, therefore, are 
associated with a compiler-generated type. 

Section 8.5.1 describes how the debugger formats (types) data for program 
locations that do not have a symbolic name and explains how you can control the 
type for those locations. 

Section 8.5.2 explains how to override the type associated with any program 
location, including a location that has a symbolic name. 


8.5.1 Defining a Type for Locations Without a Symbolic Name 


Program locations that do not have a symbolic name and, therefore, are not 
associated with a compiler-generated type have the type longword integer by 
default. Section 8.1.4 explains how to examine and deposit into such locations 
using the default type. 

The SET TYPE command enables you to change the default type. This is useful 
if you want to examine and display the contents of a location in another type, 
or if you want to deposit a value of some particular type into a location that is 
associated with another type. The possible type keywords are as follows: 
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ASCIC CONDITIONVALUE 
ASCID D_FLOAT 
ASCILn DATE_TIME 
ASCIW FLOAT 
ASCIZ G_FLOAT 
BYTE tH_FLOAT 


INSTRUCTION 

rpLONGJFLOAT 

tLON G_LON G_FLO AT 

LONGWORD 

OCTAWORD 

PACKED 


tPSL 

tPSW 

QUADWORD 

$S_FLOAT 

$T_FLOAT 

TYVE=(lype-expression) 

WORD 


tVAX specific 
i Alpha specific 

For example, the following commands set the type for locations without a 
symbolic name to, respectively, byte integer, G_floating, and ASCII with 6 bytes 
of ASCII data. Each successive SET TYPE command resets the type: 


8.5.2 


DBG> SET TYPE BYTE 
DBG> SET TYPE G_FLOAT 
DBG> SET TYPE ASCII:6 

Note that the SET TYPE command, when used without the /OVERRIDE 
qualifier, does not affect the type for program locations that have a symbolic 
name (locations associated with a compiler-generated type). 

The SHOW TYPE command identifies the current type for locations without a 
symbolic name. To restore the default type for such locations, enter the SET 
TYPE LONGWORD command. 

Overriding the Current Type 

The SET TYPE/OVERRIDE command enables you to change the type associated 
with any program location, which overrides any compiler-generated type. For 
example, after the following command is executed, an unqualified EXAMINE 
command displays the contents of only the first byte of the location specified 
and interprets the contents as byte integer data. An unqualified DEPOSIT 
command modifies only the first byte of the location specified and formats the 
data deposited as byte integer data. 

DBG> SET TYPE/OVERRIDE BYTE 

To identify the current override type, enter the SHOW TYPE/OVERRIDE 
command. To cancel the current override type and restore the normal 
interpretation of locations that have a symbolic name, enter the CANCEL 
TYPE/OVERRIDE command. 


Type qualifiers, used with the EXAMINE and DEPOSIT commands, enable you to 
override the type currently associated with a program location for the duration of 
a single EXAMINE or DEPOSIT command. The type qualifiers are as follows: 


/ASCIC 

/condition_value 

/ASCID 

/D_FLOAT 

/ASCII:/! 

/DATE_TIME 

/ASCIW 

/FLOAT 

/ASCIZ 

/G_FLOAT 

/BYTE 

f/H_FLOAT 


/INSTRUCTION 

t/LONG_FLOAT 

t/LON G_LON G_FLO AT 

/OCTAWORD 

/PACKED 

/tPSL 


/tPSW 

/QUADWORD 

t/S_FLOAT 

t/T.FLOAT 

/TASK 

/ TYPE={type-expression) 
/WORD 


fVAX specific 
tAlpha specific 

These qualifiers override any previous SET TYPE or SET TYPE/OVERRIDE 
command as well as any compiler-generated type. 
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When used with a type qualifier, the EXAMINE command displays the entity 
specified by the address expression in that type. For example: 


DBG> EXAMINE/BYTE . ! Type is 

M0D3ULINE 15 : -48 

DBG> EXAMINE/WORD . i Type is 

M0D3ULINE 15 : 464 

DBG> EXAMINE/LONG . ' Type is 

M0D3ULINE 15 : 749404624 

DBG> EXAMINE/QUAD . ! Type is 

MOD3%LINE 15 : +0130653502894178768 

DBG> EXAMINE/FLOAT . ! Type is 

MOD3%LINE 15 : 1.9117807E-38 

DBG> EXAMINE/G FLOAT . ! Type is 

MOD3%LINE 15 1.509506018605227E-300 

DBG> EXAMINE/ASCII . ! Type is 

MOD3ULINE 15 : 

DBG> 


byte integer, 
word integer, 
longword integer, 
quadword integer. 
F_floating. 
G_floating. 

ASCII string. 


When used with a type qualifier, the DEPOSIT command deposits a value of that 
type into the location specified by the address expression, which overrides the 
type associated with the address expression. 

The remaining sections provide examples of specifying integer, string, and 
user-declared types with type qualifiers and the SET TYPE command.’ 

8.5.2.1 Integer Types 

The following examples show the use of the EXAMINE and DEPOSIT commands 
with integer-type qualifiers (/BYTE, /WORD, /LONGWORD). These qualifiers 
enable you to deposit a value of a particular integer type into an arbitrary 
program location. 


DBG> SHOW TYPE 
type: long integer 
DBG> EVALU/ADDR . 

724 

DBG> DEPO/BYTE . = 1 

DBG> EXAM . 

724: 1280461057 

DBG> EXAM/BYTE . 

724: 1 

DBG> DEPO/WORD . = 2 

DBG> EXAM/WORD . 

724: 2 

DBG> DEPO/LONG 724 = 999 

DBG> EXAM/LONG 724 

724: 999 

DBG> 


! Show type for locations without 
1 a compiler-generated type. 


Current location is 724. 


! Deposit the value 1 into one byte 
1 of memory at address 724. 


! By default, 4 bytes are examined. 

! Examine one byte only. 

! Deposit the value 2 into first two 
! bytes (word) of current entity. 

! Examine a word of the current entity. 


! Deposit the value 999 into 4 bytes 
!(a longword) beginning at address 724. 
! Examine 4 bytes (longword) 

! beginning at address 724. 


8.5.2.2 


ASCII String Type 

The following examples show the use of the EXAMINE and DEPOSIT commands 
with the /ASCILn type qualifier. 

When used with the DEPOSIT command, this qualifier enables you to deposit 
an ASCII string of length n into an arbitrary program location. In the example, 
the location has a symbolic name (I) and, therefore, is associated with a compiler- 
generated integer type. The command syntax is as follows: 

DEPOSIT/ASCII:n address-expression = "ASCII string of length n" 
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The default value of n is 4 bytes. 

DBG> DEPOSIT I = "abode" ! I has compiler-generated integer type. 
IDEBUG-W-INVNUMBER, invalid numeric string 'abcde' 

! So, it cannot deposit string into I. 
DBG> DEP/ASCII:5 I = "abcde"! /ASCII qualifier overrides integer 


! type to deposit 5 bytes of 
! ASCII data. 

! Display value of I in compiler- 
! generated integer type. 

! Display value of I as 5-byte 
! ASCII string. 


DBG> EXAMINE . 
M0D3\I: 1146048327 

DBG> EXAM/ASCII:5 . 
MOD3\I: "abcde" 
DBG> 


If you want to enter several DEPOSIT/ASCII commands, you can establish an 
override ASCII type with the SET TYPE/OVERRIDE command. Subsequent 
EXAMINE and DEPOSIT commands then have the effect of specifying the /ASCII 
qualifier with these commands. For example: 

DBG> SET TYPE/OVER ASCII:5! Establish ASCII:5 as override type.) 

DBG> DEPOSIT I = "abcde" ! Can now deposit 5-byte string into I.) 

DBG> EXAMINE I ! Display value of I as 5-byte) 

MOD3\I: "abcde" ! ASCII string. 

DBG> CANCEL TYPE/OVERRIDE ! Cancel ASCII override type. 

DBG> EXAMINE I ! Display I in compiler-generated type. 

MOD3\I: 1146048327 
DBG> 


8.S.2.3 User-Declared Types 


The following examples show the use of the EXAMINE and DEPOSIT commands 
with the /TYPE ={name) qualifier. The qualifier enables you to specify a user- 
declared override type when examining or depositing. 

For example, assume that a Pascal program contains the following code, which 
declares the enumeration type COLOR with the three values RED, GREEN, and 
BLUE: 


TYPE 


COLOR = (RED,GREEN,BLUE); 


During the debugging session, the SHOW SYMBOL/TYPE command identifies 
the type COLOR as it is known to the debugger: 

DBG> SHOW SYMBOL/TYPE COLOR 
data MOD3\COLOR 

enumeration type (COLOR, 3 elements), size: 1 byte 

DBG> 

The next example displays the value at address 1000, which is not associated 
with a symbolic name. Therefore, the value 0 is displayed in the type longword 
integer, by default. 

DBG> EXAMINE 1000 
1000 : 0 
DBG> 
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The next example displays the value at address 1000 in the type COLOR. The 
preceding SHOW SYMBOL/TYPE command indicates that each enumeration 
element is stored in 1 byte. Therefore, the debugger converts the first byte of the 
longword integer value 0 at address 1000 to the equivalent enumeration value, 
RED (the first of the three enumeration values): 

DBG> EXAMINE/TYPE=(COLOR) 1000 

1000: RED 

DBG> 

The following DEPOSIT command deposits the value GREEN into address 1000 
with the override type COLOR. The EXAMINE command displays the value at 
address 1000 in the default type, longword integer: 

DBG> DEP0SIT/TYPE=(COLOR) 1000 = GREEN 
DBG> EXMINE 1000 
1000 : 1 
DBG> 

The following SET TYPE command establishes the type COLOR for locations, 
such as address 1000, that do not have a symbolic name. The EXAMINE 
command now displays the value at 1000 in the type COLOR: 

DBG> SET TYPE TYPE=(COLOR) 

DBG> EXMINE 1000 
1000: GREEN 

DBG> 
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_9 

Controlling Access to Symbols in Your 

Program 


Symbolic debugging enables you to specify variable names, routine names, and so 
on, precisely as they appear in your source code. You do not need to use numeric 
memory addresses or registers when referring to program locations. 

In addition, you can use symbols in the context that is appropriate for the 
program and its source language. The debugger supports the language 
conventions regarding data types, expressions, scope and visibility of entities, and 
so on. 

To have full access to the symbols that are associated with your program, you 
must compile and link the program using the /DEBUG command qualifier. 

Under these conditions, the way in which symbol information is passed from your 
source program to the debugger and is processed by the debugger is transparent 
to you in most cases. However, certain situations might require some action. 

For example, when you try to set a breakpoint on a routine named COUNTER, 
the debugger might display the following diagnostic message: 

DBG> SET BREAK COUNTER 

%DEBUG-E-NOSYMBOL, symbol 'COUNTER' is not in the symbol table 
DBG> 

You must then set the module where COUNTER is defined, as explained in 
Section 9.2. 

The debugger might display the following message if the same symbol X is 
defined (declared) in more than one module, routine, or other program unit: 

DBG> EXAMINE X 

%DEBUG-E-NOUNIQUE, symbol 'X' is not unique 
DBG> 

You must then resolve the symbol ambiguity, perhaps by specifying a path name 
for the symbol, as explained in Section 9.3. 

This chapter explains how to handle these and other situations related to 
accessing symbols in your program. 

The chapter discusses only the symbols (typically address expressions) that are 
derived from your source program: 

The names of entities that you have declared in your source code, such as 
variables, routines, labels, array elements, or record components. 

• The names of modules (compilation units) and shareable images that are 
linked with your program. 
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• Elements that the debugger uses to identify source code—for example, the 
specifications of source files, and source line numbers as they appear in a 
listing file or when the debugger displays source code. 

The following types of symbols are discussed in other chapters: 

• The symbols you create during a debugging session with the DEFINE 
command are covered in Section 12.4. 

• The debugger’s built-in symbols, such as the period (.) and %PC, are 
discussed throughout this manual in the appropriate context and are defined 
in Appendix B. 

Also, see Section 8.1.10 for information about how to obtain the memory 
addresses and register names associated with symbolic address expressions and 
how to symbolize program locations. 

_Note --- 

If your program was optimized during compilation, certain variables 
in the program might be removed by the compiler. If you then try to 
reference such a variable, the debugger issues a warning (see Section 5.2 
and Section 13.1). 

Before you try to reference a nonstatic (stack-local or register) variable, 
its defining routine must be active on the call stack. That is, program 
execution must be paused somewhere within the defining routine (see 
Section 7.4.3). 


9.1 Controlling Symbol Information When Compiling and Linking 

To take full advantage of symbolic debugging, you must compile and link your 
program with the /DEBUG qualifier as explained in Section 5.2. 

The following sections describe how symbol information is created and passed to 
the debugger when compiling and linking. 

9.1.1 Compiling 

When you compile a source file using the /DEBUG qualifier, the compiler creates 
symbol records for the debug symbol table (DST records) and includes them in 
the object module being created. 

DST records provide not only the names of symbols but also all relevant 
information about their use. For example: 

• Data types, ranges, constraints, and scopes associated with variables. 

• Parameter names and parameter types associated with functions and 
procedures. 

• Source-line correlation records, which associate source lines with line 
numbers and source files. 

Most compilers allow you to vary the amount of DST information put in an object 
module by specifying different options with the /DEBUG qualifier. Table 9-1 
identifies the options for most compilers (see the documentation supplied with 
your compiler for complete information). 
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Table 9-1 Compiler Options for DST Symbol Information 

Compiler Command Qualifier DST Infor mation in Object Module 

/DEBUG 1 " ' Full ’ 

/DEBUG=TRACEBACK 2 Traceback only (module names, routine names, and 

line numbers) 

/NODEBUG 3 None 

1 /DEBUG, /DEBUG=ALL, and /DEBUG=(SYMBOLS,TRACEBACK) are equivalent. 

2 /DEBUG=TRACEBACK and DEBUG=(NOSYMBOLS,TRACEBACK) are equivalent. 

3 /NODEBUG, /DEBUG=NONE, and /DEBUG=(NOSYMBOLS,NOTRACEBACK) are equivalent. 


The TRACEBACK option is a default for most compilers. That is, if you omit 
the /DEBUG qualifier, most compilers assume /DEBUG=TRACEBACK. The 
TRACEBACK option enables the traceback condition handler to translate 
memory addresses into routine names and line numbers so that it can give a 
symbolic traceback if a run-time error has occurred. For example: 

$ RON FORMS 


%PAS-F-ERRACCFIL, error in accessing file PAS$OUTPUT 
%PAS-F-ERROPECRE, error opening/creating file 
%RMS-F-FNM, error in file name 
%TRACE-F-TRACEBACK, symbolic stack dump follows 

module name routine name line rel PC abs PC 


PAS$IO_BASIC 

PAS$IO_BASIC 

PAS$IO_BASIC 

FORMS 

$ 


_PAS$C0DE 

_PAS$C0DE 

_PAS$C0DE 

FORMS 



00000192 00001CED 
0000054D 000020A8 
0000028B 00001DE6 
00000020 000005A1 


Traceback information is also used by the debugger’s SHOW CALLS command. 


9.1.2 Local and Global Symbols 


DST records contain information about all of the symbols that are defined in your 
program. These are either local or global symbols. 


Typically, a local symbol is a symbol that is referenced only within the module 
where it is defined; a global symbol is a symbol such as a routine name, 
procedure entry point, or a global data name, that is defined in one module but 
referenced in other modules. 


A global symbol that is defined in a shareable image and is referenced in 
another image (for example the main, executable image of a program) is called a 
universal symbol. When creating a shareable image, you must explicitly define 
any universal symbols as such at link time. See Section 9.4 for information about 
universal symbols and shareable images. 

Generally, the compiler resolves references to local symbols, and the linker 
resolves references to global symbols. 

The distinction between local and global symbols is discussed in various parts of 
this chapter in connection with symbol lookup and with shareable images and 
universal symbols. 
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9.1.3 Linking 

When you enter the LINK/DEBUG command to link object modules and produce 
an executable image, the linker performs several functions that affect debugging. 

• It builds a debug symbol table (DST) from the DST records contained in 
the object modules being linked. The DST is the primary source of symbol 
information during a debugging session. 

• It resolves references to global symbols and builds a global symbol table 
(GST). The GST duplicates some of the global symbol information already 
contained in the DST, but the GST is used by the debugger for symbol lookup 
under certain circumstances. 

• It puts the DST and GST in the executable image. 

• It sets flags in the executable image that cause the image activator to 
pass control to the debugger when you enter the DCL RUN command (see 
Section 5.2). 

Section 9.4 explains how to link shareable images for debugging, including how 
to define universal symbols (global symbols that are defined within a shareable 
ima ge and referenced from another image). 

Table 9—2 summarizes the level of DST and GST information passed to the 
debugger depending on the compiler or LINK command option. The compiler 
command qualifier controls the level of DST information passed to the linker. The 
LINK command qualifier controls not only how much DST and GST information 
is passed to the debugger but also whether the program can be brought under 
debugger control (see Section 5.2). 


Table 9-2 Effect of Compiler and Linker on DST and GST Symbol Information 


Compiler 

Command 

Qualifier 1 

DST Data in 
Object Module 

LINK Command 
Qualifier 2 

DST Data 

Passed 
to Debugger 

GST Data 

Passed 
to Debugger 3 

/DEBUG 

Full 

/DEBUG 

Full 

Full 

/DEBUG=TRACE 

TVaceback only 

/DEBUG 

TVaceback only 

Full 

/NODEBUG 

None 

/DEBUG 

None 

Full 

/DEBUG 

Full 

/TRACE 4 

TVaceback only 

Full 

/DEBUG=TRACE 

TVaceback only 

/TRACE 

TVaceback only 

Full 

/NODEBUG 

None 

/TRACE 

None 

Full 

/DEBUG 

Full 

/NOTRACE 5 



1 See Table 9-1 for additional information. 

2 You must also specify the /SHAREABLE qualifier when creating a shareable image (see Section 9.4). 

3 GST data includes global symbol information that is resolved at link time. GST data for an executable image includes 
the namesand valims ofglobal routines and global constants. GST data for a shareable image includes universal symbols 
(see Section 9.1.2 and Section 9.4). 

4 LINK/TRACEBACK and LINK/NODEBUG are equivalent. This is the default for the LINK command. 

5 The RUN/DEBUG command allows you to run the debugger, but if you entered the LINK/NOTRACEBACK command 
you will be unable to do symbolic debugging. 
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If you specify /NODEBUG with the compiler command and subsequently link and 
execute the image, the debugger issues the following message when the program 
is brought under debugger control: 

oDEBUG-I-NOLOCALS, image does not contain local symbols 

The previous message, which occurs whether you linked with the /TRACEBACK 
or /DEBUG qualifier, indicates that no DST has been created for that image. 
Therefore, you have access only to global symbols contained in the GST. 

If you do not specify /DEBUG with the LINK command, the debugger issues the 
following message when the program is brought under debugger control: 

IDEBUG-I-NOGLOBALS, some or all global symbols not accessible 

The previous message indicates that the only global symbol information available 
during the debugging session is information that is stored in the DST. 

These concepts are discussed in later sections. In particular, see Section 9.4 for 
additional information related to debugging shareable images. 

9.1.4 Controlling Symbol Information in Debugged Images 

Symbol records occupy space within the executable image. After you have 
debugged your program, you might want to link it again without using the 
/DEBUG qualifier to make the executable image smaller. This creates an image 
with only traceback data in the DST and with a GST. 

The LINK/NOTRACEBACK command enables you to secure the contents of an 
image from users after it has been debugged. Use this command for images that 
are to be installed with privileges (see the OpenVMS System Manager’s Manual 
and the OpenVMS System Management Utilities Reference Manual ). When you 
enter LINK/NOTRACEBACK, no symbolic information (including traceback data) 
is passed to the image. 

9.2 Setting and Canceling Modules 

You need to set a module if the debugger is unable to locate a symbol that you 
have specified (for example, a variable name X) and issues a message as in the 
following example: 

DBG> EXAMINE X 

%DEBUG-E-NOSYMBOL, symbol 'X' is not in the symbol table 
DBG> 

This section explains module setting, and the conditions under which you might 
need to set or cancel a module, using the SET MODULE and CANCEL MODULE 
commands. 

When you compile and link your program using the /DEBUG command qualifier, 
as explained in Section 9.1, complete symbol information is passed from the 
program’s source code to its executable image 

Symbol information is contained in the debug symbol table (DST) and global 
symbol table (GST) within the executable image. The DST contains detailed 
information about local and global symbols. The GST duplicates some of the 
global symbol information contained in the DST. 

To facilitate symbol searches, the debugger loads symbol information from the 
DST and GST into a run-time symbol table (RST), which is structured for efficient 
symbol lookup. Unless symbol information is in the RST, the debugger does not 
recognize or properly interpret the associated symbol. 


9-5 




Controlling Access to Symbols in Your Program 
9.2 Setting and Canceling Modules 

Because the RST takes up memory, the debugger loads it dynamically, 
anticipating what symbols you might want to reference in the course of program 
execution. The loading process is called module setting, because all symbol 
information for a given module is loaded into the RST at one time. 

When your program is brought under debugger control, all GST records are 
loaded into the RST, because global symbols must be accessible throughout the 
debugging session. Also, the debugger sets the module that contains the main 
program (the routine specified by the image transfer address, where execution is 
paused at the start of a debugging session). You then have access to all global 
symbols and to any local symbols that should be visible within the main program. 

Subsequently, whenever execution of the program is interrupted, the debugger 
sets the module that contains the routine in which execution is paused. (For 
Ada programs, the debugger also sets any module that is related by a with- 
clause or subunit relationship, as explained in the debugger’s online help. Type 
HELP Language ADA.) This enables you to reference the symbols that should be 
visible at that program location (in addition to the global symbols). This default 
mode of operation is called dynamic mode. When setting a module dynamically, 
the debugger issues a message such as the following: 

%DEBUG-I-DYNMODSET, setting module M0D4 

If you try to reference a symbol that is defined in a module that has not been set, 
the debugger warns you that the symbol is not in the RST. You must then use the 
SET MODULE command to set the module containing that symbol explicitly. For 
example: 

DBG> EXAMINE X 

%DEBUG-E-NOSYMBOL, symbol 'X' is not in the symbol table 

DBG> SET MODULE M0D3 

DBG> EXAMINE X 

MOD3\ROUT2\X: 26 

DBG> 

The SHOW MODULE command lists the modules of your program and identifies 
which modules are set. 

When a module is set, the debugger automatically allocates memory as needed by 
the RST. This can eventually slow down the debugger as more modules are set. If 
performance becomes a problem, you can use the CANCEL MODULE command 
to reduce the number of set modules, which automatically releases memory. 

Or you can disable dynamic mode by entering the SET MODE NODYNAMIC 
command. When dynamic mode is disabled, the debugger does not set modules 
automatically. Use the SHOW MODE command to determine whether dynamic 
mode is enabled or disabled. 

For additional information about module setting specific to Ada programs, see the 
debugger’s online help (type HELP Language ADA). 

Section 9.4 explains how to set images and modules when debugging shareable 
images. 
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9.3 Resolving Symbol Ambiguities 

Symbol ambiguities can occur when a symbol (for example, a variable name X) is 
denned in more than one routine or other program unit. 

In most cases, the debugger resolves symbol ambiguities automatically, by using 
the scope and visibility rules of the currently set language and the ordering of 
routine calls on the call stack, as explained in Section 9.3.1. 

However, in some cases the debugger might respond as follows when you specify 
a symbol that is defined multiple times: 

It might not be able to determine the particular declaration of the symbol 
that you intended. For example: 

DBG> EXAMINE X 

%DEBUG-W-NOUNIQUE, symbol 'X' is not unique 
DBG> 

It might reference the declaration that is visible in the current scope, which 
may not be the one you want. 

To resolve such problems, you must specify a scope where the debugger should 
search for a particular declaration of the symbol. In the following example, the 
pathname COUNTERXX uniquely specifies a particular declaration of X: 

DBG> EXAMINE C0UNTER\X 

C0UNTER\X: 14 

DBG> 

The following sections discuss scope concepts and explain how to resolve symbol 
ambiguities. 

9.3.1 Symbol Lookup Conventions 

This section explains how the debugger searches for symbols, resolving 
most potential symbol ambiguities using the scope and visibility rules of the 
programming language and also its own rules. Section 9.3.2 and Section 9.3.3 
describe supplementary techniques that you can use when necessary. 

You can specify symbols in debugger commands by using either a path name or 
the exact symbol. 

If you use a path name, the debugger looks for the symbol in the scope denoted 
by the pathname prefix (see Section 9.3.2). 

If you do not specify a pathname prefix, by default, the debugger searches the 
run-time symbol table (RST) as explained in the following paragraphs (you can 
modify this default behavior with the SET SCOPE command as explained in 
Section 9.3.3). 

First, the debugger looks for symbols in the PC scope (also known as scope 
0), according to the scope and visibility rules of the currently set language. 

This means that, typically, the debugger first looks within the block or routine 
surrounding the current PC value (where execution is currently paused). If the 
symbol is not found, the debugger searches the nesting program unit, then its 
nesting unit, and so on. The precise manner, which depends on the language, 
ensures that the correct declaration of a symbol that is defined multiple times is 
chosen. 
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However, you can reference symbols throughout your program, not just those that 
are visible in the PC scope as defined by the language. This is necessary so you 
can set breakpoints in arbitrary areas, examine arbitrary variables, and so on. 
Therefore, if the symbol is not visible in the PC scope, the debugger continues 
searching as follows. 

After the PC scope, the debugger searches the scope of the calling routine (if 
any), then its caller, and so on. Symbolically, the complete scope search list is 
denoted (0,1,2, .. . ,n), where 0 denotes the PC scope and n is the number of calls 
on the call stack. Within each scope (call frame), the debugger uses the visibility 
rules of the language to locate a symbol. 

This search list, based on the call stack, enables the debugger to differentiate 
symbols that are defined multiple times in a convenient, predictable way. 

If the symbol is still not found, the debugger searches the rest of the RST—that 
is, the other set modules and the global symbol table (GST). At this point the 
debugger does not attempt to resolve any symbol ambiguities. Instead, if more 
than one occurrence of the symbol is found, the debugger issues a message such 
as the following: 

%DEBUG-W-NOUNIQUE, symbol 'Y' is not unique 

If you have used a SET SCOPE command to modify the default symbol search 
behavior, you can restore the default behavior with the CANCEL SCOPE 
command. 

9.3.2 Using SHOW SYMBOL and Path Names to Specify Symbols Uniquely 

If the debugger indicates that a symbol reference is not unique, use the SHOW 
SYMBOL command to obtain all possible path names for that symbol, then 
specify a path name to reference the symbol uniquely. For example: 

DBG> EXAMINE COUNT 

IDEBUG-W-NOUNIQUE, symbol 'COUNT' is not unique 

DBG> SHOW SYMBOL COUNT 
data MOD7\ROUT3\BLOCKl\COUNT 
data MOD4\ROUT2\COUNT 
routine MOD2\ROUTl\ROUT3\COUNT 

DBG> EXAMINE MOD4\ROUT2\COUNT 

M0D4 \R0UT2 \C0UNT: 12 

DBG> 

The command SHOW SYMBOL COUNT lists all declarations of the symbol 
COUNT that exist in the RST. The first two declarations of COUNT are 
variables (data). The last declaration listed is a routine. Each declaration 
is shown with its pathname prefix, which indicates the path (search scope) 
the debugger must follow to reach that particular declaration. For example, 
MOD4\ROUT2\COUNT denotes the declaration of the symbol COUNT in 
routine ROUT2 of module MOD4. 

The pathname format is as follows. The leftmost element of a path name 
identifies the module containing the symbol. Moving toward the right, the path 
name lists the successively nested routines and blocks that lead to the particular 
declaration of the symbol (which is the rightmost element). 

The debugger always displays symbols with their path names, but you need to 
use path names in debugger commands only to resolve an ambiguity. 
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The debugger looks up line numbers like any other symbols you specify (by 
default, it first looks in the module where execution is paused). A common use of 
path names is for specifying a line number in an arbitrary module. For example: 

DBG> SET BREAK QUEUE_MANAGER\%LINE 26 

The SHOW SYMBOL command identifies global symbols twice, because global 
symbols are included both in the DST and in the GST. For example: 

DBG> SHOW SYMBOL X 

data ALPHA\X ! global X 

data ALPHA\BETA\X ! local X 

data X (global) ! same as ALPHA\X 

DBG> 

au^ 7 C o Se ° f a shareable ima S e ’ its global symbols are universal symbols and the 
SHOW SYMBOL command identifies universal symbols twice (see Section 9 12 
and Section 9.4). 

9.3.2.1 Simplifying Path Names 

Path names are often long. You can simplify the process of specifying path names 
in three ways: 

• Abbreviate a path name 

• Define a brief symbol for a path name 

• Set a new search scope so you do not have to use a path name 

To abbreviate a path name, delete the names of nesting program units starting 
from the left, but leave enough of the path name to specify it uniquely. For 
example, ROUT3\ COUNT is a valid abbreviated path name for the routine in the 
first example of Section 9.3.2. 

To define a symbol for a path name, use the DEFINE command. For example: 

DBG> DEFINE INTX = INT_STACK\CHECK\X 
DBG> EXAMINE INTX 

To set a new search scope, use the SET SCOPE command, which is described in 
Section 9.3.3. 

9.3.2.2 Specifying Symbols in Routines on the Call Stack 

You can use a numeric path name to specify the scope associated with a routine 
on the call stack (as identified in a SHOW CALLS display). The pathname prefix 
"0\" denotes the PC scope, the pathname prefix "1\" denotes scope 1 (the scope 
of the caller routine), and so on. 

For example, the following commands display the current values of two distinct 
declarations of Y, which are visible in scope 0 and scope 2, respectively: 

DBG> EXAMINE 0\Y 
DBG> EXAMINE 2\Y 

By default, the EXAMINE Y command signifies EXAMINE 0\Y. 

See the SET SCOPE/CURRENT command description in Section 9.3.3. That 
command enables you to reset the reference for the default scope search list 
relative to the call stack. 
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9.3.2.3 Specifying Global Symbols 

To specify a global symbol uniquely, use a backslash (\ ) as a prefix to the symbol. 
For example, the following command displays the value of the global symbol X: 

DBG> EXAMINE \X 

9.3.2.4 Specifying Routine Invocations 

When a routine is called recursively, you might need to distinguish among several 
calls to the same routine, all of which generate new symbols with identical names. 

You can include an invocation number in a path name to indicate a particular 
call to a routine. The number must be a nonnegative integer and must follow the 
name of the rightmost routine in the path name. A 0 denotes the most recent 
invocation; 1 denotes the previous invocation, and so on. For example, if PROG 
calls COMPUTE and COMPUTE calls itself recursively, and each call creates a 
new variable SUM, the following command displays the value of SUM for the 
most recent call to COMPUTE: 

DBG> EXAMINE PR0G\C0MPUTE 0\SUM 

To refer to the variable SUM that was generated in the previous call to 
COMPUTE, express the path name with a 1 in place of the 0. 

When you do not include an invocation number, the debugger assumes that the 
reference is to the most recent call to the routine (the default invocation number 
is 0). 

See the SET SCOPE/CURRENT command description in Section 9.3.3. That 
command enables you to reset the reference for the default scope search list 
relative to the call stack. 

9.3.3 Using SET SCOPE to Specify a Symbol Search Scope 

By default, the debugger looks up symbols that you specify without a pathname 
prefix by using the scope search list described in Section 9.3.1. 

The SET SCOPE command enables you to establish a new scope for symbol 
lookup so that you do not have to use a path name when referencing symbols in 
that scope. 

In the following example, the SET SCOPE command establishes the path name 
MOD4\ ROUT2 as the new scope for symbol lookup. Then, references to Y 
without a pathname prefix specify the declaration of Y that is visible in the new 
scope. 

DBG> EXAMINE Y 

%DEBUG-E-NOUNIQUE, symbol 'Y' is not unique 
DBG> SHOW SYMBOL Y 
data MOD7\ROUT3\BLOCKl\Y 
data MOD4\ROUT2\Y 

DBG> SET SCOPE MOD4\ROUT2 
DBG> EXAMINE Y 
MOD4\ROUT2\Y: 12 
DBG> 

After you enter a SET SCOPE command, the debugger applies the path name you 
specified in the command to all references that are not individually qualified with 
path names. 
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You can specify numeric path names with SET SCOPE (see Section 9.3.2.2). For 

example, the following command sets the current scope to be three calls down 
from the PC scope: 

DBG> SET SCOPE 3 

Y)u can also define a scope search list to specify the order in which the debugger 
should search for symbols. For example, the following command causes the 
debugger to look for symbols first in the PC scope (scope 0) and then in the scope 
denoted by routine ROUT2 of module MOD4: 

DBG> SET SCOPE 0, MOD4\ROOT2 

The debugger’s default scope search list is equivalent to entering the following 
command (if it existed): 

DBG> SET SCOPE 0,1,2,3, . . . ,n 

Here the debugger searches successively down the call stack to find a symbol. 

You can use the SET SCOPE/CURRENT command to reset the reference for the 
default scope search list to another routine down the call stack. For example, the 
following command sets the scope search list to be 2,3,4, ...,«: 

DBG> SET SCOPE/CURRENT 2 

To display the current scope search list for symbol lookup, use the SHOW SCOPE 
command. To restore the default scope search list (see Section 9.3.1) use the 
CANCEL SCOPE command. 

9.4 Debugging Shareable Images 

By default, your program might be linked with several Digital-supplied shareable 
images (for example, the run-time library image LIBRTL.EXE). This section 
explains how to extend the concepts described in the previous sections when 
debugging user-defined shareable images. 

A shareable image is not intended to be directly executed. A shareable image 
must first be included as input in the linking of an executable image, and then 
the shareable image is loaded at run time when the executable image is run. You 
do not have to install a shareable image to debug it. Instead, you can debug your 
own private copy by assigning a logical name to it. 

See the OpenVMS Linker Utility Manual for detailed information about linking 
shareable images. 

9.4.1 Compiling and Linking Shareable Images for Debugging 

The basic steps in compiling and linking a shareable image for debugging are as 
follows (an example follows the steps): 

1. Compile the source files for the main image and for the shareable image bv 
using the /DEBUG qualifier. 

2. Link the shareable image with the /SHAREABLE and /DEBUG command 
qualifiers and declare any universal symbols for that image. (A universal 
symbol is a global symbol that is defined in a shareable image and referenced 
in another image.) 

3. Link the shareable image against the main image by specifying the shareable 
image with the /SHAREABLE file qualifier as a linker option. Also specify 
the /DEBUG command qualifier. 
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Alpha 


4. Define a logical name to point to the local copy of the shareable image. You 
must specify the device and directory as well as the image name. Otherwise 
the image activator looks for an image of that name in the system default 
shareable image library directory, SYS$SHARE. 

5. Bring the main image under debugger control. The shareable image is loaded 
at run time. 

These steps are shown next with a simple example. In the example, MAIN.FOR 
and SUB1.FOR are the source files for the main (executable) image; SHR1.FOR 
and SHR2.FOR are the source files for the shareable image to be debugged. 

You compile the source files for each image as described in Section 9.1. 

$ FORTRAN/NOOPT/DEBUG MAIN,SUBl 
$ FORTRAN/NOOPT/DEBUG SHR1,SHR2 

On VAX processors, use the LINK command with the UNIVERSAL linker option 
to create the shareable image and specify any universal symbols. For example: 

$ LINK/SHAREABLE/DEBU G SHR l,SHR2,SYS$INPUT:/OPTIONS 
UNIVERSAL=SHR_ROUT |cwz] ♦ 

On Alpha processors, use the LINK command with the SYMBOLJVECTOR option 
to create the shareable image and specify any universal symbols. For example: 

$ LINK/SHAREABLE/DEBUG SHRl,SHR2,SYS$INPUT:/OPTIONS 
SYMBOL_VECTOR=(SHR_ROUT=PROCEDURE) gtrK] ♦ 

In the previous examples: 

• The /SHAREABLE command qualifier creates the shareable image SHR1.EXE 
from the object files SHRl.OBJ and SHR2.0BJ. 

• The /OPTIONS qualifier appended to SYS$INPUT: enables you to specify the 
universal symbol SHR_ROUT. 

• The /DEBUG qualifier builds a debug symbol table (DST) and a global symbol 
table (GST) for SHR1.EXE and puts them in that image. The GST contains 
the universal symbol SHR_ROUT. 

You have now built the shareable image SHR1.EXE in your current default 
directory. Because SHR1.EXE is a shareable image, you do not execute it 
explicitly. Instead you link SHR1.EXE against the main (executable) image: 

$ LINK/DEBUG MAIN,SUB1,SYS$INPUT:/OPTION 
SHRl .EXE/SHAREABLE JetFi/z] 

$ 

In the previous example: 

• The LINK command creates the executable image MAIN.EXE from 
MAIN.OBJ and SUBl.OBJ. 

• The /DEBUG qualifier builds a DST and a GST for MAIN.EXE and puts them 
in that image. 

• The /SHAREABLE qualifier appended to SHR1.EXE specifies that SHR1.EXE 
is to be linked against MAIN.EXE as a shareable image. 

When you execute the resulting main image, MAIN.EXE, any shareable images 
linked against it are loaded at run time. However, by default, the image activator 
looks for shareable images in the system default shareable image library 
directory, SYS$SHARE. Therefore, you must define the logical name SHRl to 
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point to SHR1.EXE in your current default directory. Be sure to specify the 
device and directory: 

$ DEFINE SHR1 SYS$DISK:[JSHR1.EXE 

now brin £ both MAIN and SHR1 under debugger control by specifying 
MAIN with the debugger RUN command (after starting the debugger): 

$ DEBUG/KEEP 

Debugger Banner and Version Number 
DBG> RON MAIN 

9.4.2 Accessing Symbols in Shareable Images 

All the concepts covered in Section 9.1, Section 9.2, and Section 9.3 apply to the 
modules of a single image, namely the main (executable) image. This section 
provides additional information that is specific to debugging shareable images. 

When you link shareable images for debugging as explained in Section 9.4.1, 
the linker builds a DST and a GST for each image. The GST for a shareable 
image contains only universal symbols. To conserve memory, the debugger builds 
an RST for an image only when that image is set, either dynamically by the 
debugger or when you use a SET IMAGE command. 

The SHOW IMAGE command identifies all shareable images that are linked with 
your program, shows which images are set, and identifies the current image (see 
Section 9.4.2.2 for a definition of the current image). Only the main image is set 
initially when you bring the program under debugger control. 

The following sections explain how the debugger sets images dynamically 
during program execution and how you can access symbols in arbitrary images 
independently of execution. 

See Section 7.4.3.4 for information about setting watchpoints in installed writable 
shareable images. 

9.4.2.1 Accessing Symbols in the PC Scope (Dynamic Mode) 

By default, dynamic mode is enabled. Therefore, whenever the debugger 
interrupts execution, the debugger sets the image and module where execution is 
paused, if they are not already set. 

Dynamic mode gives you the following access to symbols automatically: 

You can reference symbols defined in all set modules in the image where 
execution is paused. 

• You can reference any universal symbols in the GST for that image. 

By setting other modules in that image with the SET MODULE command, you 
can reference any symbol defined in the image. 

After an image is set, it remains set until you cancel it with the CANCEL 
IMAGE command. If the debugger slows down as more images and modules 
are set, use the CANCEL IMAGE command. You can also enter the SET MODE 
NODYNAMIC command to disable dynamic mode. 
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9.4.2.2 Accessing Symbols in Arbitrary Images 

The last image that you or the debugger sets is the current image. The current 
image is the debugging context for symbol lookup. Therefore, when using the 
following commands, you can reference only the symbols that are defined in the 
current image: 

DEFINE/ADDRESS 

DEFINE/VALUE 

DEPOSIT 

EVALUATE 

EXAMINE 

TYPE 

(SET,CANCEL) BREAK 
(SET,SHOW,CANCEL) MODULE 
(SET,CANCEL) TRACE 
(SET,CANCEL) WATCH 
SHOW SYMBOL 

Note that the SHOW BREAK, SHOW TRACE, and SHOW WATCH commands 
identify any breakpoints, tracepoints, or watchpoints that have been set in all 
images. 

To reference a symbol in another image, use the SET IMAGE command to make 
the specified image the current image, then use the SET MODULE command to 
set the module where that symbol is defined (the SET IMAGE command does not 
set any modules). The following sample program shows these concepts. 

The sample program consists of a main image PROG1 and a shareable image 
SHR1. Assume that you have just brought the program under debugger control 
and that execution is paused within the main program unit in image PROG1. 
Assume that you want to set a breakpoint on routine ROUT2, which is defined in 
some module in image SHR1. 

If you try to set a breakpoint on ROUT2, the debugger looks for ROUT2 in the 
current image, PROG1: 

DBG> SET BREAK ROUT2 

%DEBUG-E-NOSYMBOL, symbol 'R0UT2' is not in symbol table 
DBG> 

The SHOW IMAGE command shows that image SHR1 needs to be set: 


DBG> SHOW IMAGE 


image name 

set 

*PR0G1 

yes 

SHR1 

no 

total images: 2 

DBG> SET IMAGE SHR1 


DBG> SHOW IMAGE 


image name 

set 

PROG1 

yes 

*SHR1 

yes 


total images: 2 
DBG> 


base address end address 

00000200 000009FF 

00001000 00001FFF 

bytes allocated: 32856 

base address end address 

00000200 000009FF 

00001000 00001FFF 

bytes allocated: 41948 
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SHRl is now set and is the current image. However, because the SET IMAGE 
command does not set any modules, you must set the module where ROUT2 is 
defined before you can set the breakpoint: 

DBG> SET BREAK ROUT2 

%DEBUG-E-NOSYMBOL, symbol 'ROUT2' is not in symbol table 
DBG> SET MODULE/ALL 
DBG> SET BREAK ROUT2 
DBG> GO 

break at routine R0UT2 

10: SUBROUTINE ROUT2(A,B) 

DBG> 

Now that you have set image SHRl and all its modules and have reached the 
breakpoint at ROUT2, you can debug using the normal method (for example, step 
through the routine, examine variables, and so on). 

After you have set an image and set modules within that image, the image and 
modules remain set even if you establish a new current image. However, you 
have access to symbols only in the current image at any one time. 

9.4.2.3 Accessing Universal Symbols in Run-Time Libraries and System Images 

The following paragraphs describe how to access a universal symbol (such as 
a routine name) in a run-time library or other shareable image for which no 
symbol-table information was generated. With this information you can, for 
example, use the CALL command to execute a run-time library or system-service 
routine as explained in Section 12.7. 

Enter the SET MODULE command with the following command syntax: 

SET MODULE SHARE$image-name 
For example: 

DBG> SET MODULE SHARE$LIBRTL 

The debugger creates dummy modules for each shareable image in your program. 
The names of these shareable image modules have the prefix SHARE$. The 
command SHOW MODULE/SHARE identifies these shareable image modules as 
well as the modules in the current image. 

Once a shareable image module has been set with the SET MODULE command, 
you can access all of the image’s universal symbols. For example, the following ’ 
command lists all of the universal symbols in LIBRTL: 

DBG> SHOW SYMBOL * IN SHARE$LIBRTL 


routine SHARE$LIBRTL\STR$APPEND 
routine SHARE$LIBRTL\STR$DIVIDE 
routine S HARE $ LIBRTL\STR$ROUND 


routine SHARE$LIBRTL\LIB$WAIT 
routine SHARE$LIBRTL\LIB$GETDVI 


You can then specify these universal symbols with, for example, the CALL or SET 
BREAK command. 
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Setting a shareable image module with the SET MODULE command loads the 
universal symbols for that image into the run-time symbol table so that you can 
reference these symbols from the current image. However, you cannot reference 
other (local or global) symbols in that image from the current image. That is, 
your debugging context remains set to the current image. 
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Controlling the Display of Source Code 


The term source code refers to statements in a programming language as they 
appear in a source file. Each line of source code is also called a source line. 

This chapter covers the following topics: 

• How the debugger obtains information about source files and source lines. 

Specifying the location of a source file that has been moved to another 
directory after it was compiled. 

Displaying source lines by specifying line numbers, code address expressions, 
or search strings. 

• Controlling the display of source code at breakpoints, tracepoints, and 
watchpoints and after a STEP command has been executed. 

• Using the SET MARGINS command to improve the display of source lines 
under certain circumstances. 

The techniques described in this chapter apply to screen mode as well as line 
(noscreen) mode. Any difference in behavior between line mode and screen mode 
is identified in this chapter and in the descriptions of the commands discussed. 
(Screen mode is described in Chapter 11.) 

If your program has been optimized by the compiler, the code that is executing as 
you debug might not always match your source code. See Section 13.1 for more 
information. 

10.1 How the Debugger Obtains Source Code Information 

When a compiler processes source files to generate object modules, it assigns 
a line number to each source line sequentially. For most languages, each 
compilation unit (module) starts with line 1. For other languages like Ada, each 
source file, which might represent several compilation units, starts with line 1. 

Line numbers appear in a source listing obtained with the /LIST compile- 
command qualifier. They also appear whenever the debugger displays source 
code, either in line mode or screen mode. Moreover, you can specify line numbers 
with several debugger commands (for example, TYPE and SET BREAK). 

The debugger displays source lines only if you have specified the /DEBUG 
command with both the compile command and the LINK command. Under these 
conditions, the symbol information created by the compiler and passed to the 
debug symbol table (DST) includes source-line correlation records. For a given 
module, source-line correlation records contain the full file specification of each 
source file that contributes to that module. In addition, they associate source 
records (symbols, types, and so on) with source files and line numbers in the 
module. 
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10.2 Specifying the Location of Source Files 

The debug symbol table (DST) contains the full file specification of each source 
file when it was compiled. By default, the debugger expects a source file to be 
in the same directory it was in at compile time. If a source file is moved to a 
different directory after it is compiled, the debugger does not find it and issues a 
warning such as the following when attempting to display source code from that 
file: 

IDEBUG-W-UNAOPNSRC, unable to open source file DISK: [JONES.W0RK]PRG.F0R;2 

In such cases, use the SET SOURCE command to direct the debugger to the new 
directory. The command can be applied to all source files for your program or to 
only the source files for specific modules. 

For example, after the following command line is entered, the debugger looks for 
all source files in WORK$:[JONES.PROG3]: 

DBG> SET SOURCE W0RK$:[JONES.PR0G3] 

You can specify a directory search list with the SET SOURCE command. 

For example, after the following command line is entered, the debugger 
looks for source files first in the current default directory ([ ]) and then in 
WORK$:[JONES.PROG3]: 

DBG> SET SOURCE [], W0RK$:[JONES.PR0G3] 

If you want to apply the SET SOURCE command only to the source files for a 
given module, use the /MODULE =module-name qualifier and specify that module. 
For example, the following command line specifies that the source files for module 
SCREEN_IO are in the directory DISK2:[SMITH.SHARE] (the search of source 
files for other modules is not affected by this command): 

DBG> SET S0URCE/M0DULE=SCREEN_I0 DISK2:[SMITH.SHARE] 

To summarize, the SET SOURCE/MODULE command specifies the location of 
source files for a particular module, but the SET SOURCE command specifies 
the location of source files for modules that were not mentioned explicitly in SET 
SOURCE/MODULE commands. 

When you enter a SET SOURCE command, be aware that one of the two 
qualifiers, /LATEST or /EXACT, will always be active. The /LATEST qualifier, the 
default, directs the debugger to search for the latest version of your source files 
(the highest-numbered version in your directory). The /EXACT qualifier directs 
the debugger to search for the version last compiled (the version recorded in the 
debugger symbol table created at compile time). For example, A SET SOURCE 
/LATEST command might search for SORT.FOR;3 while a SET SOURCE/EXACT 
command might search for SORT. FOR; 1. 

Use the SHOW SOURCE command to display all source directory search lists 
currently in effect. The command displays the search lists for specific modules (as 
previously established by one or more SET SOURCE/MODULE commands) and 
the search list for all other modules (as previously established by a SET SOURCE 
command). For example: 
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DBG> SET SOURCE [PROJA],[PROJB],USERS:[PETER.PROJC] 

DBG> SET S0URCE/M0DULE=C0B0LTEST [], DISK$2:[PR0JD1 
DBG> SHOW SOURCE 

source directory search list for COBOLTEST: 

[] 

DISK$2:[PROJD] 

source directory search list for all other modules: 

[PROJA] 

[PROJB] 

USERS:[PETER.PROJC] 

DBG> 

° r ® ET s OURCE/MODULE command has been entered, the 
oHOW SOURCE command indicates that no search list is currently in effect. 

Use the CANCEL SOURCE command to cancel the effect of a previous SET 
SOURCE command. Use the CANCEL SOURCE/MODULE command to cancel 
the effect of a previous SET SOURCE/MODULE command (specifying the same 
module name). 

When a source directory search list has been canceled, the debugger again 
expects the source files corresponding to the designated modules to be in the 
same directories they were in at compile time. 

For more information about how the debugger locates source files that have been 
moved to another directory after compile time, see the SET SOURCE command 
description in online help. 

10.3 Displaying Source Code by Specifying Line Numbers 

The TYPE command enables you to display source lines by specifying compiler- 
assigned line numbers, where each line number designates a line of source 
code. 

For example, the following command displays line 160 and lines 22 to 24 of the 
module being debugged: 

DBG> TYPE 160, 22:24 
module COBOLTEST 

160: START-IT-PARA, 
module COBOLTEST 

22: 02 SC2V2 PIC S99V99 COMP VALUE 22.33. 

23: 02 SC2V2N PIC S99V99 COMP VALUE -22.33. 

24: 02 CPP2 PIC PP99 COMP VALUE 0.0012. 

DBG> 

You can display all the source lines of a module by specifying a range of line 
numbers starting from 1 and ending at a number equal to or greater than the 
largest line number in the module. 

After displaying a source line, you can display the next line in that module by 
entering a TYPE command without a line number—that is, by entering a TYPE 
command and then pressing the Return key. For example: 

DBG> TYPE 160 
module COBOLTEST 

160: START-IT-PARA. 

DBG> TYPE 
module COBOLTEST 

161: MOVE SCI TO ES0. 

DBG> 

You can then display the next line and successive lines by entering the TYPE 
command repeatedly, which lets you read through your code one line at a time. 
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To display source lines in an arbitrary module of your program, specify the 
module name with the line numbers. Use standard pathname notation that is, 
first specify the module name, then a backslash (\ ), and finally the line numbers 
(or the range of line numbers) without intervening spaces. For example, the 
following command displays line 16 of module TEST. 

DBG> TYPE TEST\16 

If you specify a module name with the TYPE command, the module must be set. 
Use the SHOW MODULE command to determine whether a particular module is 
set. Then use the SET MODULE command, if necessary (see Section 9.2). 

If you do not specify a module name with the TYPE command, the debugger 
displays source lines for the module in which execution is currently paused by 
default—that is, the module associated with the PC scope. If you have specified 
another scope with the SET SCOPE command the debugger displays source lines 
in the module associated with the specified scope. 

In screen mode, the output of a TYPE command updates the current source 
display (see Section 11.6.6). 

After displaying source lines at various locations in your program, you can 
redisplay the line at which execution is currently paused by pressing key 5 on the 
keypad (KP5). 

10.4 Displaying Source Code by Specifying Code Address 
Expressions 

The EXAMINE/SOURCE command enables you to display the source line 
corresponding to a code address expression. A code address expression denotes 
the address of a machine-code instruction and, therefore, must be one of the 
following: 

• A line number associated with one or more instructions 

• A label 

• A routine name 

• The memory address of an instruction 

You cannot specify a variable name with the EXAMINE/SOURCE command, 
because a variable name is associated with data, not with instructions. 

When you use the EXAMINE/SOURCE command, the debugger evaluates the 
address expression to obtain a memory address, determines which compiler- 
assigned line number corresponds to that address, and then displays the source 
line designated by the line number. 

For example, the following command line displays the source line associated with 
the address (declaration) of routine SWAP: 

DBG> EXAMINE/SOURCE SWAP 
module MAIN 

47: procedure SWAP(X,Y: in out INTEGER) is 

DBG> 

If you specify a line number that is not associated with an instruction, the 
debugger issues a diagnostic message. For example: 
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DBG> EXAMINE/SOURCE %LINE 6 


%DEBUG I LINEINFO, no line 6, previous line is 5, next line is 
^DEBUG-E-NOSYMBOL, symbol '%LINE 6' is not in the symbol table 
DBG> 


When using the EXAMINE/SOURCE command with a symbolic address 
expression (a line number, label, or routine), you might need to set the module 
in which the entity is defined, unless that module is already set. Use the SHOW 
MODULE command to determine whether a particular module is set Then if 
necessary, use the SET MODULE command (see Section 9.2). 

The command EXAMINE/SOURCE ,%PC displays the source line corresponding 
to the current PC value (the line that is about to be executed). For example: 

DBG> EXAMINE/SOURCE .%PC 
module C0B0LTEST 

162: DISPLAY ESO. 

DBG> 


Note the use of the contents-of operator (.), which specifies the contents of 
the entity that follows the period. If you do not use the contents-of operator 
the debugger tries to find a source line for the PC rather than for the address 
currently stored in the PC: 

DBG> EXAMINE/SOURCE %PC 

%DEBUG-W-NOSRCLIN, no source line for address 7FFF005C 
DBG> 

The following example shows the use of a numeric path name (1\) to display 
the source line at the PC value one level down the call stack (at the call to the 
routine in which execution is paused): 

DBG> EXAMINE/SOURCE ,1\%PC 

In screen mode, the output of an EXAMINE/SOURCE command updates the 
current source display (see Section 11.6.6). 

The debugger uses the EXAMINE/SOURCE command in the following contexts to 
display source code at the current PC value. 

Keypad key 5 (KP5) is bound to the following debugger command sequence: 

EXAMINE/SOURCE .%S0URCE_SC0PE\%PC; EXAMINE/INST .%INST SC0PE\%PC 

This command sequence displays the source line and the instruction at which 
execution is currently paused in the current scope. Pressing KP5 enables you to 
quickly determine your debugging context. 

The predefined source display SRC is an automatically updated display that 
executes the following built-in command every time the debugger interrupts 
execution and prompts for commands (see Section 11.2.1): 

EXAMINE/SOURCE .%S0URCE_SC0PE\%PC 

10.5 Displaying Source Code by Searching for Strings 

The SEARCH command enables you to display any source lines that contain an 
occurrence of a specified string. 

The syntax of the SEARCH command is as follows: 

S EAR C H [/ qualified , . . . ]] [range] [string] 
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The range parameter can be a module name, a range of line numbers, or a 
combination of both. If you do not specify a module name, the debugger uses the 
current scope to find source lines, as with the TYPE command (see Section 10.3). 

By default the SEARCH command displays the source line that contains the first 
(next) occurrence of a string in a specified range (SEARCH/NEXT). The command 
SEARCH/ALL displays all source lines that contain an occurrence of a string in a 
specified range. For example, the following command line displays the source line 
that contains the first occurrence of the string pro in module SCREENJO: 


DBG> SEARCH SCREEN_I0 pro 

The remaining examples use source lines from one COBOL module, in the current 
scope, to show various aspects of the SEARCH command. 

The following command line displays all source lines within lines 40 to 50 that 
contain an occurrence of the string D: 


DBG> SEARCH/ALL 40:50 D 
module C0B0LTEST 


40: 

02 

D2N 

41: 

02 

D 

42: 

02 

DN 

47: 

02 

DR0 

48: 

02 

DR5 

49: 

02 

DR10 

50: 

02 

DR15 


COMP-2 VALUE -234560000000. 

COMP-2 VALUE 222222.33. 

COMP-2 VALUE -222222.333333. 

COMP-2 VALUE 0.1. 

COMP-2 VALUE 0.000001. 

COMP-2 VALUE 0.00000000001. 
COMP-2 VALUE 0.0000000000000001. 


DBG> 

After you have found an occurrence of a string in a particular module, you can 
enter the SEARCH command with no parameters to display the source line 
containing the next occurrence of the same string in the same module. This is 
similar to using the TYPE command without a parameter to display the next 
source line. For example: 

DBG> SEARCH 42:50 D 
module COBOLTEST 

42 ; 02 DN COMP-2 VALUE -222222.333333. 

DBG> SEARCH 
module COBOLTEST 

47: 02 DR0 COMP-2 VALUE 0.1. 

DBG> 


By default, the debugger searches for a string as specified and does not interpret 
the context surrounding an occurrence of the string (this is the behavior of 
SEARCH/STRING). If you want to locate occurrences of a string that is an 
identifier in your program (for example, a variable name) and exclude other 
occurrences of the string, use the /IDENTIFIER qualifier. The command 
SEARCH/IDENTIFIER displays only those occurrences of the string that are 
bounded on either side by a character that cannot be part of an identifier in the 
current language. 


The default qualifiers for the SEARCH command are /NEXT and /STRING. If you 
want to establish different default qualifiers, use the SET SEARCH command. 
For example, after the following command is executed, the SEARCH command 
behaves like SEARCH/IDENTIFIER: 


DBG> SET SEARCH IDENTIFIER 
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Use the SHOW SEARCH command to display the default qualifiers currently in 
effect for the SEARCH command. For example: 

DBG> SHOW SEARCH 

search settings: search for next occurrence, as an identifier 
DBG> 


10.6 Controlling Source Display After Stepping and at Eventpoints 

By default, the debugger displays the associated source line when a breakpoint, 
tracepoint, or watchpoint is triggered and upon the completion of a STEP 
command. 

When you enter a STEP command, the debugger displays the source line at which 
execution is paused after the step. For example: 


DBG> STEP 

stepped to MAIN\%LINE 16 
16: RANGE := 500; 

DBG> 


When a breakpoint or tracepoint is triggered, the debugger displays the source 
line at the breakpoint or tracepoint, respectively. For example: 

DBG> SET BREAK SWAP 
DBG> GO 


break at MAIN\SWAP 

47: procedure SWAP(X,Y: in out INTEGER) is 

DBG> 

When a watchpoint is triggered, the debugger displays the source line 
corresponding to the instruction that caused the watchpoint to be triggered. 

The SET STEP [NO]SOURCE command enables you to control the display of 
source code after a step and at breakpoints, tracepoints, and watchpoints. SET 
STEP SOURCE, the default, enables source display. SET STEP NOSOURCE 
suppresses source display. For example: 

DBG> SET STEP NOSOURCE 
DBG> STEP 

stepped to MAIN\%LINE 16 
DBG> SET BREAK SWAP 
DBG> GO 


break at MAIN\SWAP 
DBG> 

You can selectively override the effect of a SET STEP SOURCE command or 
a SET STEP NOSOURCE command by using the qualifiers /SOURCE and 
/NOSOURCE with the STEP, SET BREAK, SET TRACE, and SET WATCH 
commands. 

The STEP/SOURCE command overrides the effect of the SET STEP NOSOURCE 
command, but only for the duration of that STEP command (similarly, 
STEP/NOSOURCE overrides the effect of SET STEP SOURCE for the duration of 
that STEP command). For example: 
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DBG> SET STEP NOSOURCE 
DBG> STEP/SOURCE 
stepped to MAIN\%LINE 16 

16: RANGE := 500; 

DBG> 

The SET BREAK/SOURCE command overrides the effect of the SET STEP 
NOSOURCE command, but only for the breakpoint set with that SET BREAK 
command (similarly, SET BREAK/NOSOURCE overrides the effect of SET STEP 
SOURCE for the breakpoint set with that SET BREAK command). The same 
conventions apply to the SET TRACE and SET WATCH commands. For example: 

DBG> SET STEP SOURCE 

DBG> SET BREAK/NOSOURCE SWAP 

DBG> GO 


break at MAIN\SWAP 
DBG> 

10.7 Setting Margins for Source Display 

The SET MARGINS command enables you to specify the leftmost and rightmost 
source-line character positions at which to begin and end the display of a source 
line (respectively, the left and right margins). This is useful for controlling the 
display of source code when, for example, the code is deeply indented or long lines 
wrap at the right margin. In such cases, you can set the left margin to eliminate 
indented space in the source display, and you can decrease the right margin 
setting to truncate lines and prevent them from wrapping. 

For example, the following command line sets the left margin to column 20 and 
the right margin to column 35. 

DBG> SET MARGINS 20:35 

Subsequently, only that portion of the source code that is between columns 20 and 
35 is displayed when you enter commands that display source lines (for example, 
TYPE, SEARCH, STEP). Use the SHOW MARGINS command to identify the 
current margin settings for the display of source lines. 

Note that the SET MARGINS command affects only the display of source lines. 

It does not affect the display of other debugger output (for example, output from 
an EXAMINE command). 

The SET MARGINS command is useful mostly in line (noscreen) mode. In screen 
mode, the SET MARGINS command has no effect on the display of source lines 
in a source display, such as the predefined display SRC. 
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Using Screen Mode 


Screen mode enables you to see more information more conveniently than the 
default, line-oriented display mode. In screen mode, you display different types of 
ata in separate areas of the screen. For example, you may display your source 
code in the top left half of the screen, the contents of the registers in the top right 
half, debugger output in the middle, and diagnostic messages at the bottom near 
your interactive input. 

To enable screen mode, press PF3 on the keypad (or enter the SET MODE 
SCREEN command). To return to line-oriented debugging, press PF1 PF3 (or 
enter the SET MODE NOSCREEN command). In screen mode, to re-create the 
default layout of various windows, press the keypad sequence PF4 MINUS (PF4 
followed by the MINUS key (-)). 

Screen mode output is best displayed on VT-series terminals with higher numbers 
t an VT52, and on workstations running VWS. The larger screen of workstations 
is particularly suitable to using a number of displays for different purposes. 

This chapter covers the following topics: 

Screen mode concepts and terminology used throughout the chapter 

• The predefined displays SRC, OUT, PROMPT, INST, and REG, which are 
automatically available when you enter screen mode 

• Scrolling, hiding, deleting, moving, and resizing a display 

• Creating a new display 

• Specifying a display window 

• The different kinds of displays and how to use them 

• Directing various types of debugger output to different displays by assigning 
display attributes 

A sample display configuration that shows a possible use of screen mode 

• Saving the current state of your screen displays 

Changing your terminal screen’s height and width during a debugging session 
and the effect on display windows 

• Screen-related debugger built-in symbols 

• Screen dimensions and predefined windows 

• Internationalization of screen mode 
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Many screen mode commands are bound to keypad keys. For key definitions, see 
Appendix A. 

_ Note -- 

This chapter provides information common to programs that run in one or 
several processes. See Chapter 14 for additional information specific to 
multiprocess programs. 


11.1 Concepts and Terminology 

A display is a group of text lines. The text might be lines from a source file, 
assembly-language instructions, the values contained in registers, your input to 
the debugger, various types of debugger output, or program input and output. 

You view a display through its window, which can occupy any rectangular area 
of the screen. Because a display’s window is typically smaller than the display, 
you can scroll the window up, down, right, and left across the display text to view 
any part of the display. 

Figure 11-1 is an example of screen mode that shows three displays. The name 
of each display (SRC, OUT, and PROMPT) appears at the top left corner of its 
window. It serves both as a tag on the display itself and as a name for future 
reference in commands. 


Figure 11-1 Default Screen Mode Display Configuration 



Displays SRC, OUT, and PROMPT have the following basic characteristics: 

• Display SRC is a source-code display (it is displaying FORTRAN code in the 
example shown in Figure 11—1). SRC’s current window is the upper half of 
the screen. Like other display windows, SRC’s window can be changed to 
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accommodate different display layouts. The name of the module whose source 
code is displayed, SQUARES$MAIN, is to the right of the display name. 

• Display OUT, located in a window directly below SRC, shows the output of 
debugger commands. 

• Display PROMPT, at the bottom of the screen, shows the debugger prompt 
and debugger input. 

Figure 11-1 is the default display configuration that is established when you first 
invoke screen mode. SRC, OUT, and PROMPT are three of the five predefined 
displays that the debugger provides by default when you enter screen mode (see 
Section 11.2). You can create additional displays. 

Every display has a memory buffer, whose size is independent of the window 
size and can be adjusted. Displays that hold source-code or assembly-language 
instructions let you see all the lines of source code of the associated module or all 
of the instructions of the associated routine, regardless of the size of the memory 
buffer. This is because the necessary information is paged into the buffer as 
needed. For other displays, such as display OUT, the buffer size defines how 
much text the display can hold. If you add more text to the display, the oldest 
text lines are discarded to make room for the new text. 

Conceptually, displays are placed on the screen as on a pasteboard. The display 
that is most recently referenced in a command is put on top of the pasteboard by 
default. Therefore, depending on the window locations, the displays that you have 
referenced recently might overlay or hide other displays (as on a pasteboard). 

The debugger maintains a display list, which is the pasting order of displays. 
Several keypad key definitions use the display list to cycle through the displays 
currently on the pasteboard. 

Every display belongs to a display kind (see Section 11.6). The display kind 
determines what type of information the display can capture and display; for 
example, source code, assembly-language instructions, and debugger output of 
various types. The display kind also determines how the contents of the display 
are generated. 

The contents of a display are generated in two ways. Some displays are 
automatically updated. Their definition includes a command list that is executed 
whenever the debugger gains control from the program. The output of the 
command list forms the contents of those displays. Display SRC belongs to that 
category: it is automatically updated so that an arrow centered in the window 
shows the source line at which execution is currently paused. 


Other displays, for example display OUT, derive their contents from commands 
you enter interactively. If you create a display of this general category, you 
must first select it (with the SELECT command) as the target display for one or 
more types of output before anything can be written to it. This is also known as 
assigning one or more display attributes to a display (see Section 11.7). 


The names of any attributes assigned to a display appear to the right of the 
display name, in lowercase letters. In Figure 11-1, SRC has the source and 
scroll attributes (SRC is the current source display and the current scrolling 
display), OUT has the output attribute (it is the current output display), 
and so on. Note that, although SRC is automatically updated by its own built-in 
command, it can also receive the output of certain interactive commands (such as 
EXAMINE/SOURCE) because it has the source attribute. 
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11.1 Concepts and Terminology 

The concepts introduced in this section are developed in more detail in the rest of 
this chapter. 

11.2 Debugger Predefined Displays 

The debugger provides the following predefined displays that you can use to 
capture and display different kinds of data: 

SRC, the predefined source display 
OUT, the predefined output display 
PROMPT, the predefined prompt display 
INST, the predefined instruction display 

On VAX processors, the debugger provides REG, the predefined register display. 

When you enter screen mode, the debugger puts SRC in the top half of the screen, 
PROMPT in the bottom sixth, and OUT between SRC and PROMPT, as shown in 
Figure 11-1. Displays INST and REG are initially removed from the screen by 
default. 

If after rearranging displays and windows, you want to re-create this default 
configuration, press BLUE MINUS on the keypad (PF4 followed by the MINUS 
(-) key). 

The basic features of the predefined displays are described in the next sections. 
As explained in other parts of this chapter, you can change certain characteristics 
of these displays, such as the buffer size or display attributes. You can also create 
additional displays similar to the predefined displays. 

To display summary information about the characteristics of any display, use the 
SHOW DISPLAY command. 

11.2.1 Predefined Source Display (SRC) 

_Note -- 

See Chapter 10 for information about how to make source code available 
for display during a debugging session. 


The predefined display SRC (see Figure 11-1) is an automatically updated source 
display. 

You can use SRC to display source code in two basic ways: 

• By default, SRC automatically displays the source code for the module in 
which execution is currently paused. This enables you to quickly determine 
your current debugging context. 

• In addition, because SRC has the source attribute by default, you can use 
it to display the source code for any part of your program as explained in 
Section 11.2.1.1. 

The name of the module whose source code is displayed is shown at the right 
of the display name, SRC. The numbers displayed at the left of the source code 
are the compiler-generated line numbers, as they might appear in a compiler¬ 
generated listing file. 
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As you execute the program under debugger control, SRC is automatically 
updated whenever execution is paused. The arrow in the leftmost column 
indicates the source line to be executed next. Specifically, execution is paused at 
the first instruction associated with that source line. Thus, the line indicated by 
the arrow corresponds to the current program counter (PC) value. The PC is a 
register that contains the memory address of the next instruction to be executed. 

If the debugger cannot locate source code for the routine in which execution is 
paused (because, for example, the routine is a run-time library routine), it tries 
to display source code in the next routine down on the call stack for which source 
code is available. When displaying source code for such a routine, the debugger 
issues the following message: 

%DEBUG-I-SOURCESCOPE, Source lines not available for .0\%PC. 

Displaying source in a caller of the current routine. 

Figure 11-2 shows this feature. The source display shows that a call to routine 
TYPE is currently active. TYPE corresponds to a FORTRAN run-time library 
procedure. No source code is available for that routine, so the debugger displays 
the source code of the calling routine. The output of a SHOW CALLS command 
shown in the output display, identifies the routine where execution is paused and 
the call sequence leading to that routine. 

In such cases, the arrow in the source window identifies the line to which 
execution returns after the routine call. Depending on the source language and 

coding style, this might be the line that contains the call statement or the next 
line. 


Figure 11-2 Screen Mode Source Display When Source Code Is Not Available 



If your program was optimized during compilation, the source code displayed 
in SRC might not always represent the code that is actually executing. The 
predefined instruction display INST is useful in such cases, because it shows the 
exact instructions that are executing. See Section 11.2.4. 
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The built-in command that automatically updates display SRC is 
EXAMINE/SOURCE ,%SOURCE_SCOPE\%PC. For information about the 
EXAMINE/SOURCE command, see Section 10.4. The built-in debugger symbol 
%SOURCE_SCOPE denotes a scope and has the following properties: 

• By default %SOURCE_SCOPE denotes scope 0, which is the scope of the 
routine where execution is currently paused. 

• If you have reset the scope search list relative to the call stack by means of 
the SET SCOPE/CURRENT command (see Section 11.2.1.2), %SOURCE_ 
SCOPE denotes the current scope specified (the scope of the routine at the 
start of the search list). 

• If source code is not available for the routine in the current scope, 
%SOURCE_SCOPE denotes scope n, where n is the first level down the 
call stack for which source code is available. 

11.2.1.1 Displaying Source Code in Arbitrary Program Locations 

You can use display SRC to display source code throughout your program, if 
source code is available for display: 

• You can scroll through the entire source display by pressing KP2 (scroll down) 
or KP8 (scroll up) as explained in Section 11.3.1. This enables you to view 
any of the source code within the module in which execution is paused. 

• You can display the source code for any routine that is currently on the call 
stack by using the SET SCOPE/CURRENT command (see Section 11.2.1.2). 

• Because SRC has the source attribute, you can display source code throughout 
your program by using the TYPE and EXAMINE/SOURCE commands: 

— To display arbitrary source lines, use the TYPE command (see 
Section 10.3). 

- To display the source line associated with a code location (for example, 
a routine declaration), use the EXAMINE/SOURCE command (see 
Section 10.4). 

When using the TYPE or EXAMINE/SOURCE command, make sure that the 
module in which you want to view source code is set first. Use the SHOW 
MODULE command to determine whether a particular module is set. Then 
use the SET MODULE command, if necessary (see Section 9.2). 

After manipulating the contents of display SRC, you can redisplay the location 
at which execution is currently paused (the default behavior of SRC) by pressing 
KP5. 

11.2.1.2 Displaying Source Code for a Routine on the Call Stack 

The command SET SCOPE/CURRENT lets you display the source code for any 
routine that is currently on the call stack. For example, the following command 
updates display SRC so that it shows the source code for the caller of the routine 
in which execution is currently paused: 

DBG> SET SCOPE/CURRENT 1 

To reset the default scope for displaying source code, enter the command CANCEL 
SCOPE. The command causes display SRC to show the source code for the routine 
at the top of the call stack where execution is paused. 
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11.2.2 Predefined Output Display (OUT) 

Figure 11-1 and Figure 11-2 show some typical debugger output in the predefined 
display OUT. 

Display OUT is a general-purpose output display. By default, OUT has the output 
attribute so it displays any debugger output that is not directed to the source 
display SRC or the instruction display INST. For example, if display INST is 
not displayed or does not have the instruction attribute, any output that would 
otherwise update display INST is shown in display OUT. 

By default, OUT does not display debugger diagnostic messages (these appear 
in the PROMPT display). You can assign attributes to OUT so that it captures 
debugger input and diagnostics as well as normal output (see Section 11.7). 

11.2.3 Predefined Prompt Display (PROMPT) 

The predefined display PROMPT is the display in which the debugger prompts 
for input. Figure 11-1 and Figure 11-2 show PROMPT in its default location, the 
bottom sixth of the screen. 

By default, PROMPT has the program and error attributes in addition to the 
prompt attribute. Therefore, by default, the debugger forces program output to 
PROMPT and prints diagnostic messages to that display. 

PROMPT has different properties and restrictions than other displays. This is to 
eliminate possible confusion when manipulating that display: 

• The debugger always keeps PROMPT on top of the display pasteboard so it 
cannot be hidden by another display. You cannot hide PROMPT (with the 
DISPLAY/HIDE command), or remove PROMPT from the pasteboard (with 
the DISPLAY/REMOVE command), or permanently delete PROMPT (with the 
CANCEL DISPLAY command). 

• PROMPT can have the scroll attribute so that it can be made the default 
target display for the MOVE and EXPAND commands. However, you cannot 
scroll PROMPT. 

• You can move PROMPT anywhere on the screen, expand it to fill the full 
screen height, and contract it down to two lines. PROMPT must always 
occupy the full width of the screen. Therefore, you cannot move, expand, or 
contract PROMPT horizontally. 

The debugger alerts you if you try to move or expand a display such that it is 
hidden by PROMPT. 

11.2.4 Predefined Instruction Display (INST) 

-- Note ___ 

By default, the predefined instruction display INST is not shown on the 
screen and does not have the instruction attribute (see Section 11.2.4.1 
and Section 11.2.4.2). 


Display INST is an automatically updated instruction display. It shows the 
decoded instruction stream of your program. This is the exact code that is 
executing, including the effects of any compiler optimization. 
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A VAX example is shown in Figure 11-3. ♦ 

This type of display is useful when debugging code that has been optimized. In 
such cases some of the code being executed might not match the source code that 
is shown in a source display. See Section 13.1 for information about the effects of 
optimization. 

You can use INST in two basic ways: 

• By default, INST automatically displays the decoded instructions for the 
routine in which execution is currently paused. This enables you to quickly 
determine your current debugging context. 

• In addition, if INST has the instruction attribute, you can use it to display 
the decoded instructions for any part of your program as explained in 
Section 11.2.4.2. 

The name of the routine whose instructions are displayed is shown at the right of 
the display name, INST. The numbers displayed at the left of the instructions are 
the compiler-generated source line numbers. 

As you execute the program under debugger control, INST is updated 
automatically whenever execution is paused. The arrow in the leftmost column 
points to the instruction at which execution is paused. This is the instruction 
that will be executed next and whose address is the current PC value. 


Figure 11-3 Screen Mode Instruction Display (VAX example) 



EXAMINE/INSTRUCTION command, see Section 8.3.1. 
symbol %INST_SCOPE denotes a scope and has the following properties: 
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• By default %INST_SCOPE denotes scope 0, which is the scope of the routine 
where execution is currently paused. 

If you have reset the scope search list relative to the call stack by means of 
the SET SCOPE/CURRENT command (see, Section 11.2.4.3), %INST_SCOPE 
denotes the current scope specified (the scope of the routine at the start of the 
search list). 

11.2.4.1 Displaying the Instruction Display 

By default, display INST is marked as removed (see Section 11.3.2) from the 
display pasteboard and is not visible. To show display INST, use one of the 
following methods: 

• Press KP7 to place displays SRC and INST side by side. This enables you to 
compare the source code and the decoded instruction stream. 

• Press PF1 KP7 to place displays INST and REG side by side. 

• Enter the DISPLAY INST command to place INST in its default or most 
recently defined location (see Section 11.3.2). 

11.2.4.2 Displaying Instructions in Arbitrary Program Locations 

You can use display INST to display decoded instructions throughout your 
program as follows: 

• You can scroll through the entire instruction display by pressing KP2 (scroll 
down) or KP8 (scroll up) as explained in Section 11.3.1. This enables you to 
view any instruction within the routine in which execution is paused. 

• You can display the instruction stream for any routine that is currently 
on the call stack by using the SET SCOPE/CURRENT command (see 
Section 11.2.4.3). 

• If INST has the instruction attribute, you can display the instructions 
for any code location throughout your program by using the EXAMINE 
/INSTRUCTION command as follows: 

- To assign INST the instruction attribute, use the SELECT 
/INSTRUCTION INST command (see Section 11.6.2 and Section 11.7). 

Note that the instruction attribute is automatically assigned to INST 
when you display it by pressing either KP7 or PF1 KP7. 

- To display the instructions associated with a code location (for example, 
a routine declaration), use the EXAMINE/INSTRUCTION command (see 
Section 8.3.1). 

If no display has the instruction attribute, the output of an EXAMINE 
/INSTRUCTION command is directed at display OUT. 

After manipulating the contents of display INST, you can redisplay the location 
at which execution is currently paused (the default behavior of INST) by pressing 
KP5. 

11.2.4.3 Displaying Instructions for a Routine on the Call Stack 

The SET SCOPE/CURRENT command lets you display the instructions for any 
routine that is currently on the call stack. For example, the following command 
updates display INST so that it shows the instructions for the caller of the routine 
in which execution is currently paused: 

DBG> SET SCOPE/CDRRENT 1 
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To reset the default scope for displaying instructions, enter the CANCEL SCOPE 
command. The command causes display INST to show the instructions for the 
routine at the top of the call stack where execution is paused. 


11.2.5 Predefined Register Display (REG) (VAX Only) 




On VAX processors, the predefined register display REG shows the current 
values, in hexadecimal format, of the general registers (RO to Rll, AP, FP, SP, 
PC), the four condition code bits (C, V, Z, and N) of the processor status longword 
(PSL), and as many of the top stack values as can be displayed in the window 
(see Figure 11-4). 


Figure 11-4 Screen Mode Register Display 


— SRC: module SQUARES$MAIN — scroll-sourc 
3: C 


4 

5 

6 

7 

8 
9 

10 

11 

12 

13 


Read the input array 
OPEN(UNIT=8, FILE='DATAF 
READ(8,*) N, (INARR(I), 

— Square all non-zero e 
K = 0 

DO 10 I = 1, N 
IF(INARR(I) .NE. 0) THEN 
K = K + 1 
OUTARR(K) = INAR 

END IF 


— OUT- output -- 

stepped to SQUARES$MAIN\%LINE 4 
stepped to SQUARES$MAIN\%LINE 5 
stepped to SQUARES$MAIN\%LINE 8 
SQUARES$MAIN\I: 5 

SQUARES$MAIN\K: 0 

SQUARES$MAIN\N: 4 

— PROMPT — error-program-prompt 
DBG> STEP 

DBG> EXAMINE I,K,N 
DBG> 


REG- 


R0 :00000000 
R1 :00000008 
R2 :00000000 
R3 :7FF35994 
:00000000 
:00000000 
:7FF35649 
: 8012F9E9 
:7FFECA52 
:7FFECC5A 


R4 

R5 

R6 

R7 

R8 

R9 


R10:7FFED7D4 


Rll:000004A0 
AP :7FF359CC 
FP :7FF35980 
SP :7FF35980 
PC :0000064D 
PSL: C:0 Z:0 
PSL: V:0 N:0 
@SP:00000000 
+04:08000000 
+08:7FF359CC 
+0C:7FF359B8 


+10:0002019B 
+14:7FFE2BDC 
+18:000009FF 
+1C:00000005 
+20:00000600 
+24:00000000 
+28:00000001 
+2C:0000000D 
+30:7FF359CC 
+34:00000000 
+38:00020073 


ZK-6506-GE 


The register values displayed are for the routine in which execution is currently 
paused. The values are updated whenever the debugger takes control. Any 
changed values are highlighted. 

REG is initially marked as removed (see Section 11.3.2) from the display 
pasteboard and is not visible. You must use the DISPLAY command (or press 
PFl KP7) to show the REG display. Pressing PF1 KP7 enables you to place REG 
next to display INST. 

If the register window is made larger, the debugger fills the remaining space with 
information contained in the user call stack. 

REG does not display the current values of the vector registers. To display data 
contained in vector registers or vector control registers in screen mode, use a DO 
display. (See Section 11.6.1.) 
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11.2.5.1 Displaying Register Values for a Routine on the Call Stack 

The SET SCOPE/CURRENT command lets you display the register values 
associated with any routine that is currently on the call stack. For example, the 
o owing command updates display REG so that it shows the register values for 
the caller of the routine in which execution is currently paused: 

DBG> SET SCOPE/CURRENT 1 

To reset the default scope for displaying register values, enter the CANCEL 
SCOPE command. This command causes display REG to show the register values 
tor the routine at the top of the call stack, where execution is paused. ♦ 

11.3 Manipulating Existing Displays 

This section explains how to perform the following functions: 

• Use the SELECT and SCROLL commands to scroll a display. 

Use the DISPLAY command to show, hide, or remove a display; the CANCEL 
DISPLAY command to permanently delete a display; and the SHOW 
DISPLAY command to identify the displays that currently exist and their 
order in the display list. 

• Use the MOVE command to move a display across the screen. 

• Use the EXPAND command to expand or contract a display. 

Section 11.5 and Section 11.6 discuss more advanced techniques for modifying 
existing displays with the DISPLAY command—how to change the display 
window and the type of information displayed. 

11.3.1 Scrolling a Display 

A display usually has more lines of text (and possibly longer lines) than can 
be seen through its window. The SCROLL command lets you view text that is 
hidden beyond a window’s border. You can scroll through all displays except for 
the PROMPT display. 

The easiest way to scroll displays is with the keypad keys, described later in this 
section. Using the relevant commands is explained first. 

You can specify a display explicitly with the SCROLL command. Typically 
however, you first use the SELECT/SCROLL command to select the current 
scrolling display. This display then has the scroll attribute and is the default 
display for the SCROLL command. You then use the SCROLL command with 
no parameter to scroll that display up or down by a specified number of lines, or 
to the right or left by a specified number of columns. The direction and distance 
scrolled are specified with the command qualifiers (/UP:n, /RIGHT.ra, and so on). 

In the following example, the SELECT command selects display OUT as the 
current scrolling display (/SCROLL can be omitted because it is the default 
qualifier); the SCROLL command then scrolls OUT to reveal text 18 lines down: 

DBG> SELECT OUT 
DBG> SCROLL/DOWN:18 

Several useful SELECT and SCROLL command lines are assigned to keypad keys 
(See Appendix A for a keypad diagram): 

Pressing KP3 assigns the scroll attribute to the next display in the display 
list after the current scrolling display. To select a display as the current 
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scrolling display, press KP3 repeatedly until the word "scroll" appears on the 
top line of that display. 

• Press KP8, KP2, KP6, or KP4 to scroll up, down, right, or left, respectively. 

The amount of scroll depends on which key state you use (DEFAULT, GOLD, 
or BLUE). 

11.3.2 Showing, Hiding, Removing, and Canceling a Display 

The DISPLAY command is the most versatile command for creating and 
manipulating displays. In its simplest form, the command puts an existing 
display on top of the pasteboard where it appears through its current window. 

For example, the following command shows the display INST through its current 
window: 

DBG> DISPLAY INST 

Pressing KP9, which is bound to the DISPLAY %NEXTDISP command, enables 
you to achieve this effect conveniently. The built-in function %NEXTDISP 
signifies the next display in the display list. (Appendix B identifies all screen- 
related built-in functions.) Each time you press KP9, the next display in the list 
is put on top of the pasteboard in its current window. 

By default the top line of display OUT (which identifies the display) coincides 
with the bottom line of display SRC. If SRC is on top of the pasteboard, its bottom 
line hides the top line of OUT (keep this in mind when using the DISPLAY 
command and associated keypad keys to put various displays on top of the 
pasteboard). 

To hide a display at the bottom of the pasteboard, use the DISPLAY/HIDE 
command. This command changes the order of that display in the display list. 

To remove a display from the pasteboard so that it is no longer seen (yet is not 
permanently deleted), use the DISPLAY/REMOVE command. To put a removed 
display back on the pasteboard, use the DISPLAY command. 

To delete a display permanently, use the CANCEL DISPLAY command. To 
re-create the display, use the DISPLAY command as described in Section 11.4. 

Note that you cannot hide, remove, or delete the PROMPT display. 

To identify the displays that currently exist, use the SHOW DISPLAY command. 
They are listed according to their order on the display list. The display that is on 
top of the pasteboard is listed last. 

For more information about the DISPLAY options, see the DISPLAY command 
description in online help. Note that the DISPLAY command accepts optional 
parameters that let you modify other characteristics of existing displays, namely 
the display window and the type of information displayed. The techniques are 
discussed in Section 11.5 and Section 11.6. 

11.3.3 Moving a Display Across the Screen 

Use the MOVE command to move a display across the screen. The qualifiers 
/UP:ra, /DOWN.n, /RIGHT:n, and /LEFT:n specify the direction and the number of 
lines or columns by which to move the display. If you do not specify a display, the 
current scrolling display is moved. 

The easiest way to move a display is by using keypad keys: 

• Press KP3 repeatedly as needed to select the current scrolling display. 


11-12 




Using Screen Mode 
11.3 Manipulating Existing Displays 


11.3.4 


• Put the keypad in the MOVE state, then press KP8, KP2, KP4, or KP6 to 
move the display up, down, left, or right, respectively. See Appendix A. 

Expanding or Contracting a Display 

Hf® ^ COmmand t0 ex P and or contract a display. The qualifiers /UP:n, 

OWN:n, /RIGHT:n, and /LEFT:n specify the direction and the number of lines 
or columns by which to expand or contract the display (to contract a display, 
specify negative integer values with these qualifiers). If you do not specify a 
display, the current scrolling display is expanded or contracted. 


The easiest way to expand or contract a display is to use the keypad keys: 

Press KP3 repeatedly as needed to select the current scrolling display. 

• Put the keypad in the EXPAND or CONTRACT state, then press KP8, KP2, 
KP4, or KP6 to expand or contract the display vertically or horizontally See 
Appendix A. 


The PROMPT display cannot be contracted (or expanded) horizontally. Also, it 
cannot be contracted vertically to less than two lines. 


11.4 Creating a New Display 

To create a new screen display, use the DISPLAY command. The basic syntax is 
as follows: 


DISPLAY display-name [AT window-specification] [display-kind] 

The display name can be any name that is not already used to name a display 
(use the SHOW DISPLAY command to identify all existing displays). A newly 
created display is placed on top of the pasteboard, on top of any existing displays 
(except for the predefined PROMPT display, which cannot be hidden). The display 
name appears at the top left corner of the display window. 

Section 11.5 explains the options for specifying windows. If you do not provide a 
window specification, the display is positioned in the upper or lower half of the 
screen, alternating between these locations as you create new displays. 

Section 11.6 explains the options for specifying display kinds. If you do not 
specify a display kind, an output display is created. 

For example, the following command creates a new output display named OUT2. 
The window associated with OUT2 is either the top or bottom half of the screen. 

DBG> DISPLAY 0UT2 


The following command creates a new DO display named EXAM_XY that is 
located in the right third quarter (RQ3) of the screen. This display shows the 
current value of variables X and Y and is updated whenever the debugger gains 
control from the program. 

DBG> DISPLAY EXAM_XY AT RQ3 DO (EXAMINE X,Y) 

For more information, see the DISPLAY command description in online help. 
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11.5 Specifying a Display Window 

Display windows can occupy any rectangular portion of the screen. 

You can specify a display window when you create a display with the DISPLAY 
command. You can also change the window currently associated with a display 
by specifying a new window with the DISPLAY command. When specifying a 
window, you have the following options: 

• Specify a window in terms of lines and columns. 

• Use the name of a predefined window, such as HI. 

• Use the name of a window definition previously established with the SET 
WINDOW command. 

Each of these techniques is described in the following sections. When specifying 
windows, keep in mind that the PROMPT display always remains on top of the 
display pasteboard and, therefore, occludes any part of another display that 
shares the same region of the screen. 

Display windows, regardless of how specified, are dynamic. This means that, if 
you use a SET TERMINAL command to change the screen height or width, the 
window associated with a display expands or contracts in proportion to the new 
screen height or width. 

11.5.1 Specifying a Window in Terms of Lines and Columns 

The general form of a window specification is {start-line,line-count[,start- 
column,column-count]). For example, the following command creates the output 
display CALLS and specifies that its window be 7 lines deep starting at line 10, 
and 30 columns wide starting at column 50: 

DBG> DISPLAY CALLS AT (10,7,50,30) 

If you do not specify start-column or column-count, the window occupies the full 
width of the screen. 

11.5.2 Using a Predefined Window 

The debugger provides many predefined windows. These have short, symbolic 
names that you can use in the DISPLAY command instead of having to specify 
lines and columns. For example, the following command creates the output 
display ZIP and specifies that its window be RH1 (the top right half of the 
screen): 

DBG> DISPLAY ZIP AT RH1 

The SHOW WINDOW command identifies all predefined window definitions as 
well as those you create with the SET WINDOW command. 

11.5.3 Creating a New Window Definition 

The predefined windows should be adequate for most situations, but you can 
also create a new window definition with the SET WINDOW command. This 
command, which has the following syntax, associates a window name with a 
window specification: 

SET WINDOW window-name AT (start-line,line-coun1[, start-col,col-counf\) 
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After creating a window definition, you can use its name (like that of a predefined 
window) in a DISPLAY command. In the following example, the window 
definition MIDDLE is established. That definition is then used to display 
OUT through the window MIDDLE. 

DBG> SET WINDOW MIDDLE AT (9,4,30,20) 

DBG> DISPLAY OUT AT MIDDLE 

To identify all current window definitions, use the SHOW WINDOW command 
To delete a window definition, use the CANCEL WINDOW command. 


11.6 Specifying the Display Kind 


Every display has a display kind. The display kind determines the type of 
information a display contains and how that information is generated. 

Typically, you specify a display kind when you use the DISPLAY command to 
create a new display (if you do not specify a display kind, an output display is 
created). You can also use the DISPLAY command to change the display kind of 
an existing display with the following keywords: 

DO ( command-list ) 

INSTRUCTION 
INSTRUCTION ( command ) 

OUTPUT 

REGISTER 

SOURCE 

SOURCE ( command ) 

The contents of a register display are generated and updated automatically 
by the debugger. The contents of other kinds of displays are generated by 
commands, and these display kinds fall into two general groups. 

A display that belongs to one of the following display kinds has its contents 
updated automatically according to the command or command list you supply 
when defining that display: 

DO (i command-list) 

INSTRUCTION {command) 

SOURCE (< command) 

The command list specified is executed each time the debugger gains control 
from your program, if the display is not marked as removed. The output of the 
commands forms the new contents of the display. If the display is marked as 
removed, the debugger does not execute the command list until you view that 
display (marking that display as unremoved). 

A display that belongs to one of the following display kinds derives its contents 
from commands that you enter interactively: • 

INSTRUCTION 

OUTPUT 

SOURCE 

To direct^bugger output to a specific display in this group, you must first select 
it with the SELECT command. The technique is explained in the following 
sections and in Section 11.7. After a display is selected for a certain type of 
output, the output from your commands forms the contents of the display. 
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The default size of the memory buffer associated with any newly created display 
is 64 lines. For source and instruction displays, the size of the buffer on y 
afTects performance. In the case of a source display, source files are paged in as 
necessary as you scroll through the module. In the case of an instruction display, 
the instructions are decoded from the image as necessary as you scroll through 
the routine. 

For output and DO displays, the buffer size defines how many lines of text the 
display holds. If you add more text to the display, the oldest lines are discarded 
to make room for the new text. You can use the /SIZE qualifier on the DISPLAY 
command to change the buffer size. 

11.6.1 DO (Command[; ... ]) Display Kind 

A DO display is an automatically updated display. The commands in the 
command list are executed in the order listed each time the debugger gains 
control from your program. Their output forms the contents of the display and 
erases any previous contents. 

For example, the following command creates the DO display CALLS at window 
Q3. Each time the debugger gains control from the program, the SHOW CALLS 
command is executed and the output is displayed in CALLS, replacing any 
previous contents. 

DBG> DISPLAY CALLS AT Q3 DO (SHOW CALLS) 

The following command creates a DO display named V2_DISP that shows the 
contents of elements 4 to 7 of the vector register V2 (using FORTRAN array 
syntax). The display is automatically updated whenever the debugger gains 
control from the program: 

DBG> DISPLAY V2_DISP AT RQ2 DO (EXAMINE %V2(4:7)) 

11.6.2 INSTRUCTION Display Kind 

An instruction display shows the output of an EXAMINE/INSTRUCTION 
command within the instruction stream of a routine. Because the instructions 
displayed are decoded from the image being debugged and show the exact code 
that is executing, this kind of display is particularly useful in helping you debug 
optimized code (see Section 13.1). 

In the display, one line is devoted to each instruction. Source-line numbers 
corresponding to the instructions are displayed in the left column. The instruction 
at the location being examined is centered in the display and is marked by an 
arrow in the left column. 

Before anything can be written to an instruction display, you must select it as the 
current instruction display with the SELECT/INSTRUCTION command. 

In the following example, the DISPLAY command creates the instruction display 
INST2 at RH1 The SELECT/INSTRUCTION command then selects INST2 as 
the current instruction display. When the EXAMINE/INSTRUCTION X command 
is executed, window RH1 fills with the instruction stream surrounding the 
location denoted by X. The arrow points to the instruction at location X, which is 
centered in the display. 

DBG> DISPLAY INST2 AT RH1 INSTRUCTION 
DBG> SELECT/INSTRUCTION INST2 
DBG> EXAMINE/INSTRUCTION X 

Each subsequent EXAMINE/INSTRUCTION command updates the display. 


11-16 




Using Screen Mode 
11.6 Specifying the Display Kind 


11.6.3 INSTRUCTION (Command) Display Kind 

This is an instruction display that is automatically updated with the output of 
the command specified. That command, which must be an 

EXAMINE/INSTRUCTION command, is executed each time the debugger gains 
control from your program. B 

For example, the following command creates the instruction display INST3 at 
time the dehn Sger gains control, the built-in command 
display NE/INST ^ UCTI0N %INST - SC0PE \ %p C is executed, updating the 

DBG> DISPLAY INST3 AT RS45 INSTRUCT (EX/INST .%INST_SCOPE\%PC) 

This command creates a display that functions like the predefined display INST 
The built-in EXAMINE/INSTRUCTION command displays the instruction at the 
current PC value in the current scope (see Section 11.2.4). 

If an automatically updated instruction display is selected as the current 
instruction display, it is updated like a simple instruction display by an 

interactive EXAMINE/INSTRUCTION command (in addition to being updated by 
its built-in command). 


11.6.4 OUTPUT Display Kind 

An output display shows any debugger output that is not directed to another 
isplay. New output is appended to the previous contents of the display. 

Before anything can be written to an output display, it must be selected as 
the current output display with the SELECT/OUTPUT command or as the 
current error display with the SELECT/ERROR command, or as the current 
input display with the SELECT/INPUT command. See Section 11.7 for more 
information about using the SELECT command with output displays. 

In the following example, the DISPLAY command creates the output display 
OUT2 at window T2 (the display kind OUTPUT can be omitted from this 
example, because it is the default kind). The SELECT/OUTPUT command then 
selects OUT2 as the current output display. These two commands create a display 
that functions like the predefined display OUT: 

DBG> DISPLAY 0UT2 AT T2 OUTPUT 
DBG> SELECT/OUTPUT 0UT2 

OUT2 now collects any debugger output that is not directed to another display 
For example: 


• The output of a SHOW CALLS command goes to OUT2. 

If no instruction display has been selected as the current instruction display 
the output of an EXAMINE/INSTRUCTION command goes to OUT2. 

By default, debugger diagnostic messages are directed to the PROMPT 
display. They can be directed to OUT2 with the SELECT/ERROR command. 
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11.6.5 REGISTER Display Kind 

On VAX processors, a register display is an automatically updated display that 
shows the current values, in hexadecimal format, of the general registers (RO 
to Rll AP FP, SP, and PC), the four condition code bits (C,V, Z, and N) ot the 
processor status longword (PSL), and as many of the top call stack values as can 
be displayed in the window (see Figure 11-4). 

The register values displayed are for the routine in which execution is currently 
paused. The values are updated whenever the debugger takes control. Any 
changed values are highlighted. 



A register display does not display the current values of the vector registers. To 
display data contained in vector registers or vector control registers in screen 
mode, use a DO display. (See Section 11.6.!.)♦ 


Alpha 


On Alpha processors, there is no register display in screen mode. However, you 
can create a DO display that shows the values in specific registers. For example 
the following command creates a display named REG at the top right quadrant of 


the screen: 


DBG> DISPLAY MY REG AT RH1 DO (EXAMINE %F0, %F1) 


This display shows the contents of floating-point registers FO and FI whenever 
the debugger regains control from the program. ♦ 

11.6.6 SOURCE Display Kind 

A source display shows the output of a TYPE or EXAMINE/SOURCE command 
within the source code of a module, if that source code is available. Source ine 
numbers are displayed in the left column. The source line that is the output of 
the command is centered in the display and is marked by an arrow in the left 
column. If a range of lines is specified with the TYPE command, the lines are 
centered in the display, but no arrow is shown. 

Before anything can be written to a source display, you must select it as the 
current source display with the SELECT/SOURCE command. 

In the following example, the DISPLAY command creates the source display 
SRC2 at Q2. The SELECT/SOURCE command then selects SRC2 as the current 
source display. When the TYPE 34 command is executed, window RH1 fills with 
the source code surrounding line 34 of the module being debugged. The arrow 
points to line 34, which is centered in the display. 

DBG> DISPLAY SRC2 AT Q2 SOURCE 
DBG> SELECT/SOURCE SRC2 
DBG> TYPE 34 


Each subsequent TYPE or EXAMINE/SOURCE command updates the display. 

11.6.7 SOURCE (Command) Display Kind 

This is a source display that is automatically updated with the output of the 
command specified. That command, which must be an EXAMINE/SOURCE or 
TYPE command, is executed each time the debugger gains control from your 


program. 

For example, the following command creates a source display SRC3 at window 
RS45. Each time the debugger gains control, the built-in command EXAMINE 
/SOURCE ,%SOURCE_SCOPE\ %PC is executed, updating the display. 


DBG> DISPLAY SRC3 AT RS45 SOURCE (EX/SOURCE .%SOURCE_SCOPE\%PC) 
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ms command creates a display that functions like the predefined display SRC. 
The built-in EXAMINE/SOURCE command displays the source line for the 
current PC value in the current scope (see Section 11.2.1). 

If an automatically updated source display is selected as the current source 
isplay, it is updated like a simple source display by an interactive 

EXAMINE/SOURCE or TYPE command (in addition to being updated by its 
built-in command). 


11.6.8 PROGRAM Display Kind 

The PROMPT display belongs to the program display kind. Note that PROMPT is 

the only display of that kind. You cannot specify that display kind in a DISPLAY 
command. 


To avoid possible confusion, the PROMPT display has several restrictions (see 
Section 11.2.3). 


11.7 Assigning Display Attributes 

In screen mode, the output from commands you enter interactively is directed 
to various displays according to the type of output and the display attributes 
assigned to these displays. For example, debugger diagnostic messages go to the 
display that has the error attribute (the current error display). By assigning 
one or more attributes to a display, you can mix or isolate different kinds of 
information. 

The attributes have the following names: 

error 

input 

instruction 

output 

program 

prompt 

scroll 

source 

When a display is assigned an attribute, the name of that attribute appears 
in lowercase letters on the top border of its window to the right of the display 
name. Note that the scroll attribute does not affect debugger output but is used 
to control the default display for the SCROLL, MOVE, and EXPAND commands. 

By default, attributes are assigned to the predefined displays as follows: 

• SRC has the source and scroll attributes 

• OUT has the output attribute 

• PROMPT has the prompt, program, and error attributes 

To assign an attribute to a display, use the SELECT command with the qualifier 
of the same name as the attribute. In the following example, the DISPLAY 
command creates the output display ZIP. The SELECT/OUTPUT command 
then selects ZIP as the current output display—the display that has the output 
attribute. After this command is executed, the word "output" disappears from 
the top border of the predefined output display OUT and appears instead on 
display ZIP, and all the debugger output formerly directed to OUT is now directed 
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DBG> DISPLAY ZIP OUTPUT 
DBG> SELECT/OUTPUT ZIP 

You can assign specific attributes only to certain display kinds. The following 
list identifies each of the SELECT command qualifiers, its effect, and the display 
kinds to which you can assign that attribute: 


SELECT 

Qualifier 

/ERROR 


/INPUT 

/INSTRUCTION 


/OUTPUT 


/PROGRAM 


/PROMPT 

/SCROLL 


Description __ 

Selects the specified display as the current error display. Directs 

any subsequent debugger diagnostic message to that display It 
must be either an output display or the PROMPT display. If no 
display is specified, selects the PROMPT display as the current 
error display. 


Selects the specified display as the current input display. Echoes 
any subsequent debugger input in that display. It must be an 
output display. If no display is specified, unselects the current 
input display: debugger input is not echoed to any display. 


Selects the specified display as the current instruction display. 
Directs the output of any subsequent EXAMINE/INSTRUCTION 
command to that display. It must be an instruction display. 
Keypad key sequence PF4 COMMA selects the next instruction 
display in the display list as the current instruction display. If no 
display is specified, unselects the current instruction display: no 
display has the instruction attribute. 


Selects the specified display as the current output display. Directs 
any subsequent debugger output to that display, except where a 
particular type of output is being directed to another display (such 
as diagnostic messages going to the current error display). The 
specified display must be either an output display or the PROMr I 
display. Keypad key sequence PF1 KP3 selects the next output 
display in the display list as the current output display. If no 
display is specified, selects the PROMPT display as the current 
output display. 


Selects the specified display as the current program display. 
Tries to force any subsequent program input or output to that 
display. Currently, only the PROMPT display can be specified. 
If no display is specified, unselects the current program display: 
program input and output are no longer forced to the PROMPT 
display. 


Selects the specified display as the current prompt display where 
the debugger prompts for input. Currently, only the PROMPT 
display can be specified. You cannot unselect the PROMPT 
display. 


Selects the specified display as the current scrolling display. 
Makes that display the default display for any subsequent 
SCROLL, MOVE, or EXPAND command. You can specify any 
display (however, note that the PROMPT display cannot be 
scrolled). The /SCROLL qualifier is the default if you do not 
specify a qualifier with the SELECT command. Key KP3 selects 
as the current scrolling display the next display in the display 
list after the current scrolling display. If no display is specified, 
unselects the current scrolling display: no display has the scroll 
attribute. 
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SELECT 

Qualifier 

Description 

/SOURCE 

Selects the specified display as the current source display. Directs 
the output of any subsequent TYPE or EXAMINE/SOURCE 
command to that display. It must be a source display Keypad 
key sequence PF4 KP3 selects the next source display in the 
display list as the current source display. If no display is specified 
unselects the current source display: no display has the source ’ 
attribute. 


Subject to the restrictions listed, a display can have several attributes. In the 
preceding example, ZIP was selected as the current output display. In the next 
example, ZIP is further selected as the current input, error, and scrolling display. 
After these commands are executed, debugger input, output, and diagnostics 

are logged in ZIP in the proper sequence as they occur, and ZIP is the current 
scrolling display. 

DBG> SELECT/INPUT/ERROR/SCROLL ZIP 

J id *S£ the dispiays currently selected for each of the display attributes, use 
the SHOW SELECT command. 

If you use the SELECT command with a particular qualifier but without 
specifying a display name, the effect is typically to deassign that attribute (to 
unselect the display that had the attribute). The exact effect depends on the 
attribute, as described in the preceding table. 

11.8 Sample Display Configuration 

How to best use screen mode depends on your personal style and on what type of 
error you are looking for. You might be satisfied to use the predefined displays. If 
you have access to a larger screen, you might want to create additional displays 
for various purposes. The following example might give you some ideas. 

Assume you are debugging in a high-level language and are interested in tracing 
the execution of your program through several routine calls. 

First set up the default screen configuration—that is, SRC in HI, OUT in 
S45, and PROMPT in S6 (the keypad key sequence PF4 MINUS gives this 

configuration). SRC shows the source code of the module in which execution is 
paused. 

The following command creates a source display named SRC2 in RH1 that shows 
the PC value at scope 1 (one level down the call stack, at the call to the routine 
in which execution is paused): 

DBG> DISPLAY SRC2 AT RH1 SOURCE (EXAMINE/SOURCE .1\%PC) 

Thus the left half of your screen shows the currently executing routine and the 
right half shows the caller of that routine. 

I he <S^ Wing command creates a D0 dis P la y named CALLS at S4 that executes 
the SHOW CALLS command each time the debugger gains control from the 
program: 

DBG> DISPLAY CALLS AT S4 DO (SHOW CALLS) 


11-21 






Using Screen Mode 

11.8 Sample Display Configuration 


Because the top half of OUT is now hidden by CALLS, make OUT’s window 
smaller as follows: 

DBG> DISPLAY OUT AT S5 

You can create a similar display configuration with instruction displays instead of 
source displays. 

11.9 Saving Displays and the Screen State 

The SAVE command enables you to make a snapshot of an existing display and 
save that copy as a new display. This is useful if, for example, you later want to 
refer to the current contents of an automatically updated display (such as a DO 
display). 

In the following example, the SAVE command saves the current contents of 
display CALLS into display CALLS4, which is created by the command: 

DBG> SAVE CALLS AS CALLS4 

The new display is removed from the pasteboard. To view its contents use the 
DISPLAY command: 

DBG> DISPLAY CALLS4 

The EXTRACT command has two uses. First, it enables you to save the contents 
of a display in a text file. For example, the following command extracts the 
contents of display CALLS, appending the resulting text to the file COB34.TXT: 

DBG> EXTRACT/APPEND CALLS COB34 

Second, the EXTRACT/SCREEN JAYOUT command enables you to create a 
command procedure that can later be executed during a debugging session 
to re-create the previous state of the screen. In the following example, the 
EXTRACT/SCREENLAYOUT command creates a command procedure with the 
default specification SYS$DISK:[ ]DBGSCREEN.COM. The file contains all the 
commands needed to re-create the current state of the screen. 

dbg> extract/screen_layout 

DBG> 0DBGSCREEN 

Note that you cannot save the PROMPT display as another display, or extract it 
into a file. 

11.10 Changing the Screen Height and Width 

During a debugging session, you can change the height or width of your terminal 
screen. One reason might be to accommodate long lines that would wrap if 
displayed across 80 columns. Or, if you are at a workstation, you might want to 
reformat your debugger window relative to other windows. 

To change the screen height or width, use the SET TERMINAL command. 

The general effect of the command is the same whether you are at a VT-senes 
terminal or at a workstation. 

In this example, assume you are using a workstation window in its default 
emulated VTlOO-screen mode, with a screen size of 24 lines by 80 columns. 

You have started the debugger and are using it in screen mode. You now want 
to take advantage of the larger screen. The following command increases the 
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screen height and width of the debugger window to 35 lines and 110 columns 
respectively: 

DBG> SET TERMINAL/PAGE:35/WIDTH:110 

By default, all displays are dynamic. A dynamic display automatically adjusts 
its window dimensions in proportion when a SET TERMINAL command 
changes the screen height or width. This means that, when using the SET 
TERMINAL command, you preserve the relative positions of your displays. The 
/[NOJDYNAMIC qualifier on the DISPLAY command lets you control whether 
or not a display is dynamic. If a display is not dynamic, it does not change 
its window coordinates after you enter a SET TERMINAL command (you can 
then use the DISPLAY, MOVE, or EXPAND commands, or various keypad key 
combinations, to move or resize a display). 

To see the current terminal width and height being used by the debugger, use the 
SHOW TERMINAL command. 

Note that the debugger’s SET TERMINAL command does not affect the terminal 
screen size at DCL level. When you exit the debugger, the original screen size is 
maintained. 

11.11 Screen-Related Built-In Symbols 

The following built-in symbols are available for specifying displays and screen 
parameters in language expressions: 

• %SOURCE_SCOPE—To display source code. %SOURCE_SCOPE is described 
in Section 11.2.1. 

• %INST_SCOPE—To display instructions. %INST_SCOPE is described in 
Section 11.2.4. 

• %PAGE, % WIDTH—To specify the current screen height and width. 

• %CURDISP, %CURSCROLL, %NEXTDISP, %NEXTINST, %NEXTOUTPUT 
%NEXTSCROLL, %NEXTSOURCE-To specify displays in the display list. ’ 

11.11.1 Screen Height and Width 

The built-in symbols %PAGE and %WIDTH return, respectively, the current 
height and width of the terminal screen. These symbols can be used in various 
expressions, such as for window specifications. For example, the following 
command defines a window named MIDDLE that occupies a region around the 
middle of the screen: 

DBG> SET WINDOW MIDDLE AT (IPAGE/4,%PAGE/2,%WIDTH/4,IWIDTH/2) 

11.11.2 Display Built-In Symbols 

Each time you refer to a specific display with a DISPLAY command, the display 
list is updated and reordered, if necessary. The most recently referenced display 
is put at the tail of the display list, since that display is pasted last on the 
pasteboard (you can identify the display list by entering a SHOW DISPLAY 
command). 

You can use display built-in symbols to specify displays relative to their positions 
in the display list. These symbols, listed as follows, enable you to refer to 
displays by their relative positions in the list instead of by their explicit names. 
The symbols are used mainly in keypad key definitions or command procedures. 
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Display symbols treat the display list as a circular list. Therefore, you can enter 
commands that use display symbols to cycle through the display list until you 
reach the display you want. 


%CURDISP 

%CURSCROLL 

%NEXTDISP 


%NEXTINST 


The current display. This is the display most recently referenced 
with a DISPLAY command—the least occluded display. 

The current scrolling display. This is the default display for the 
SCROLL, MOVE, and EXPAND commands, as well as for the 
associated keypad keys (KP2, KP4, KP6, and KP8). 

The next display in the list after the current display. The next 
display is the display that follows the topmost display. Because 
the display list is circular, this is the display at the bottom of the 
pasteboard—the most occluded display. 

The next instruction display in the display list after the current 
instruction display. The current instruction display is the display 
that receives the output from the EXAMINE/INSTRUCTION 
commands. 


%NEXTOUTPUT The next output display in the display list after the current output 
display. An output display receives debugger output that is not 
already directed to another display. 

%NEXTSCROLL The next display in the display list after the current scrolling 
display. 


%NEXTSOURCE The next source display in the display list after the current source 
display. The current source display is the display that receives the 
output from the TYPE and EXAMINE/SOURCE commands. 


11.12 Screen Dimensions and Predefined Windows 

On a VT-series terminal, the screen consists of 24 lines by 80 or 132 columns. On 
a workstation, the screen is larger in both height and width. The debugger can 
accommodate screen sizes up to 100 lines by 255 columns. 

The debugger has many predefined windows that you can use to position displays 
on the screen. The SHOW WINDOW command identifies all predefined and user- 
defined windows. The predefined windows are expressed in terms of fractions 
of the screen dimensions (for example, quarters, halves, and so on). Therefore, 
the positions and dimensions of the predefined windows that are indicated by the 
SHOW WINDOW command are adjusted for the screen dimensions. 

In addition to the full height and width of the screen, the predefined windows 
include all possible regions that result from dividing the screen vertically into 
halves, thirds, quarters, sixths, and eighths, and horizontally into left and right 
halves. 

The following conventions apply to the names of predefined windows. The 
prefixes L and R denote left and right windows, respectively. Other letters denote 
the full screen (FS) or fractions of the screen height (H: half, T: third, Q: quarter, 
S: sixth, E: eighth). The trailing numbers denote specific fractions of the screen 
height, starting from the top. For example: 

• Windows Tl, T2, and T3 occupy the top, middle, and bottom thirds of the 
screen, respectively. 

• Window RH2 occupies the right bottom half of the screen. 

• Window LQ23 occupies the left middle two quarters of the screen. 

• Window S45 occupies the fourth and fifth sixths of the screen. 
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The horizontal boundaries (start-column, column-count) of the predefined 
windows for the default terminal screen width of 80 columns are as follows: 

• Left-hand windows: (1,40) 

• Right-hand windows: (42,39) 

The vertical boundaries (start-line, line-count) of the predefined windows for the 
default terminal screen height of 24 lines are as follows: 


Window Name 

Start-line,Line-count 

Window Location 

FS 

(1,23) 

Full screen 

HI 

(1,11) 

Top half 

H2 

(13,11) 

Bottom half 

T1 

(1,7) 

Top third 

T2 

(9,7) 

Middle third 

T3 

(17,7) 

Bottom third 

Q1 

(1,5) 

Top quarter 

Q2 

(7,5) 

Second quarter 

Q3 

(13,5) 

Third quarter 

Q4 

(19,5) 

Bottom quarter 

SI 

(1,3) 

Top sixth 

S2 

(5,3) 

Second sixth 

S3 

(9,3) 

Third sixth 

S4 

(13,3) 

Fourth sixth 

S5 

(17,3) 

Fifth sixth 

S6 

(21,3) 

Bottom sixth 

El 

(1,2) 

Top eighth 

E2 

(4,2) 

Second eighth 

E3 

(7,2) 

Third eighth 

E4 

(10,2) 

Fourth eighth 

E5 

(13,2) 

Fifth eighth 

E6 

(16,2) 

Sixth eighth 

E7 

(19,2) 

Seventh eighth 

E8 

(22,2) 

Bottom eighth 


11.13 Internationalization of Screen Mode 

You can enable country-specific features for screen mode by defining logical 
names, as follows: 

• DBG$SMGSHR — For specifying the Screen Management (SMG) shareable 
image. The debugger uses the SMG shareable image in its implementation of 
screen mode. Asian variants of the SMG shareable image handle multibyte 
characters. Hence, if an Asian variant of SMG is used by the debugger, the 
screen mode interface to the debugger will be able to display and manipulate 
multibyte characters. 
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Define the DBG$SMGSHR logical name as follows: 

$ DEFINE/JOB DBG$SMGSHR <name_of_Asian_SMG> 

<namejof_Asian_SMG> varies according to the variants of Asian OpenVMS. 
For example, the name of the Asian SMG in Japanese OpenVMS is 
JSY$SMGSHR.EXE. 

• SMG$DEFAULT_CHARACTER_SET — For the Asian SMG and multibyte 
characters. This logical need only be defined if DBG$SMGSHR has been 
defined. See the documentation on Asian or Japanese screen management 
routines for details on how to define this logical name. 
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Additional Convenience Features 


This chapter describes the following debugger convenience features not described 
elsewhere in this manual: 

• Using debugger command procedures 

• Using an initialization file for a debugging session 

• Logging a debugging session into a file 

Defining symbols to represent commands, address expressions, or values 

• Assigning debugger commands to function keys 

• Using control structures to enter commands 

• Calling arbitrary routines linked with your program 

12.1 Using Debugger Command Procedures 

A debugger command procedure is a sequence of commands contained in a file. 
You can direct the debugger to execute a command procedure to re-create a 
debugging session, to continue a previous session, or to avoid typing the same 
debugger commands many times during a debugging session. You can pass 
parameters to command procedures. 

As with DCL command procedures, you execute a debugger command procedure 
by preceding its file specification with an at sign (@). The @ is the execute 
procedure command. 

Debugger command procedures are especially useful when you regularly perform 
a number of standard setup debugger commands, as specified in a debugger 
initialization file (see Section 12.2). You can also use a debugger log file as a 
command procedure (see Section 12.3). 

12.1.1 Basic Conventions 

The following is a sample debugger command procedure named BREAK7.COM: 

! ***** Debugger Command Procedure BREAK7.COM ***** 

SET BREAK/AFTER:3 %LINE 120 DO (EXAMINE K,N,J,X(K); GO) 

SET BREAK/AFTER:3 %LINE 160 DO (EXAMINE K,N,J,X(K),S; GO) 

SET BREAK %LINE 90 ' 

When you execute this command procedure with the execute procedure (@) 
command, the commands listed in the procedure are executed in the order they 
appear. 

The rules for entering commands in command procedures are listed in the 
debugger’s online help (type HELP Command_Format). 

You can pass parameters to a command procedure. See Section 12.1.2 for 
conventions on passing parameters. 
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You can enter the execute procedure (@) command like any other debugger 
command: directly from the terminal, from within another command procedure, 
from within a DO clause in a command such as SET BREAK, or from within a 
DO clause in a screen display definition. 

If you do not supply a full file specification with the execute procedure (@) 
command, the debugger assumes SYS$DISK:[ ]DEBUG.COM as the default file 
specification for command procedures. For example, enter the following command 
line to execute command procedure BREAK7.COM, located in your current 
default directory: 

DBG> 0BREAK7 

The SET ATSIGN command enables you to change any or all fields of the default 
file specification, SYS$DISK:[ 1DEBUG.COM. The SHOW ATSIGN command 
identifies the default file specification for command procedures. 

By default, commands read from a command procedure are not echoed. If you 
enter the SET OUTPUT VERIFY command, all commands read from a command 
procedure are echoed on the current output device, as specified by DBG$OUTPUT 
(the default output device is SYS$OUTPUT). Use the SHOW OUTPUT command 
to determine whether commands read from a command procedure are echoed or 
not. 

If the execution of a command in a command procedure results in a diagnostic 
of severity warning or greater, the command is aborted but execution of the 
command procedure continues at the next command line. 

12.1.2 Passing Parameters to Command Procedures 

As with DCL command procedures, you can pass parameters to debugger 
command procedures. However, the technique is different in several respects. 

Subject to the conventions described here, you can pass as many parameters as 
you want to a debugger command procedure. The parameters can be address 
expressions, commands, or value expressions in the current language. You must 
surround command strings in quotation marks ( ), and you must separate 
parameters by commas (,). 

A debugger command procedure to which you pass parameters must contain a 
DECLARE command line that binds each actual (passed) parameter to a formal 
parameter (a symbol) declared within the command procedure. 

The DECLARE command is valid only within a command procedure. Its syntax 
is as follows: 

DECLARE p-name:p-kind[, p-name:p-kind[, . . . ]] 

Each p-name.p-kind pair associates a formal parameter (p-name) with a 
parameter kind (p-kind). The valid p-kind keywords are as follows: 

ADDRESS Causes the actual parameter to be interpreted as an address expression. 

COMMAND Causes the actual parameter to be interpreted as a command. 

VALUE Causes the actual parameter to be interpreted as a value expression in 

the current language. 

The following example shows what happens when a parameter is passed to 
a command procedure. The command DECLARE DBG:ADDRESS, within 
command procedure EXAM.COM, declares the formal parameter DBG. The 
actual parameter passed to EXAM.COM is interpreted as an address expression. 
The command EXAMINE DBG displays the value of that address expression. The 
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command SET OUTPUT VERIFY causes the commands to echo when they are 
read by the debugger. 

i ***** Debugger Command Procedure EXAM.COM ***** 

SET OUTPUT VERIFY 
DECLARE DBG:ADDRESS 
EXAMINE DBG 

executes EXAM.COM by passing the actual parameter 
ARR24. Within EXAM.COM, ARR24 is interpreted as an address expression (an 
array variable, in this case). 

DBG> 0EXAM ARR24 

%DEBUG-I-VERIFYIC, entering command procedure EXAM 
DECLARE DBG:ADDRESS 
EXAMINE DBG 
PROG_8\ARR24 
( 1 ) 

( 2 ) 

(3) 

(4) 

(5) 

( 6 ) 

(7) 

( 8 ) 

(9) 

( 10 ) 

( 11 ) 

( 12 ) 

(13) 

(14) 

(15) 

(16) 

(17) 

(18) 

(19) 

( 20 ) 

( 21 ) 

( 22 ) 

(23) 

(24) 


Mark A. Hopper 
Rudy B. Hopper 
Tim B. Hopper 
Don C. Hopper 
Mary D. Hopper 
Jeff D. Hopper 
Nancy G. Hopper 
Barbara H. Hopper 
Lon H. Hopper 
Dave H. Hopper 
Andy J. Hopper 
Will K. Hopper 
Art L. Hopper 
Jack M. Hopper 
Karen M. Hopper 
Tracy M. Hopper 
Wanfang M. Hopper 
Jeff N. Hopper 
Nancy 0. Hopper 
Mike R. Hopper 
Rick T. Hopper 
Dave W. Hopper 
Jim W. Hopper 
Robert Z. Hopper 
%DEBUG-I-VERIFYIC, exiting command procedure EXAM 
DBG> 


Each p-name\p-kind pair specified by a DECLARE command binds one parameter. 
For example, if you want to pass five parameters to a command procedure, you 
need five corresponding p-name:p-kind pairs. The pairs are always processed in 
the order in which you specify them. 

For example, the next command procedure, EXAM_GO.COM, accepts two 
parameters: an address expression (L) and a command string (M). The address 
expression is then examined and the command is executed: 

i ***** Debugger Command Procedure EXAM GO.COM ***** 

DECLARE L:ADDRESS, M:COMMAND 
EXAMINE L; M 


The following example shows how you can execute EXAM_GO.COM by passing a 
variable X to be examined and a command @DUMP.COM to be executed: 

DBG> @EXAM_GO X, "@DUMP" 
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The %PARCNT built-in symbol, which can be used only within a command 
procedure, enables you to pass a variable number of parameters to a command 
procedure. The value of %PARCNT is the number of actual parameters passed to 
the command procedure. 

The %PARCNT built-in symbol is shown in the following example. The command 
procedure, VAR.DBG, contains the following lines: 

i ***** Debugger Command Procedure VAR.DBG ***** 

SET OUTPUT VERIFY 

! Display the number of parameters passed: 

EVALUATE %PARCNT , 

! Loop as needed to bind all passed parameters and obtain their values. 

FOR I = 1 TO %PARCNT DO (DECLARE X:VALUE; EVALUATE X) 

The following command line executes VAR.DBG, passing the parameters 12, 37, 
and 45: 

DBG> 0VAR.DBG 12,37,45 

%DEBUG-I-VERIFYIC, entering command procedure VAR.DBG 
! Display the number of parameters passed: 

EVALUATE %PARCNT 
3 

! Loop as needed to bind all passed parameters 
! and get their values: 

FOR I = 1 TO %PARCNT DO (DECLARE X:VALUE; EVALUATE X) 

12 

37 

45 

%DEBUG-I-VERIFYIC, exiting command procedure VAR.DBG 
DBG> 

When VAR.DBG is executed, %PARCNT has the value 3. Therefore, the FOR 
loop within VAR.DBG is repeated 3 times. The FOR loop causes the DECLARE 
command to bind each of the three actual parameters (starting with 12) to a new 
declaration of X. Each actual parameter is interpreted as a value expression in 
the current language, and the EVALUATE X command displays that value. 

12.2 Using a Debugger Initialization File 

A debugger initialization file is a command procedure, assigned the logical name 
DBG$INIT, that the debugger automatically executes at debugger startup. Every 
time you start the debugger, the commands contained in the file are automatically 
executed. 

An initialization file contains any command lines you might always enter at 
the start of a debugging session to either tailor your debugging environment or 
control the execution of your program in a predetermined way from run to run. 

For example, you might have a file DEBUG_START4.COM containing the 
following commands: 
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i ***** Debugger Initialization File DEBUG_START4.COM ***** 

SET°0UTPUT 9 L0G 9 SeSSi ° n int ° default l0 9 file (SYS$DISK:[JDEBUG.LOG) 

I 

. Echo commands as they are read from command procedures: 

SET OUTPUT VERIFY ^ 

i 

SE^SoS^e'iMSMiJ^SmLI 11 d8faUlt dir6Ct0r y' USe [SMITH.SHARE] 

! Invoke screen mode: 

SET MODE SCREEN 

i 

! Define the symbol SB as the SET BREAK command: 

DEFINE/COMMAND SB = "SET BREAK" 

l 

! Assign the SHOW MODULE * command to KP7: 

DEFINE/KEY/TERMINATE KP7 "SHOW MODULE *" 

To make this file a debugger initialization file, use the DCL command DEFINE 
For example: 

$ DEFINE DBGSINIT WORK:[JONES.DBGCOMFILES]DEBUG_START4.COM 

12.3 Logging a Debugging Session into a File 

A debugger log file maintains a history of a debugging session. During the 
debugging session, each command entered and the resulting debugger output are 
stored in the file. The following is an example of a debugger log file: 

SHOW OUTPUT 

!noverify, terminal, noscreen log, logging to DSK2:[JONES.P71DEBUG LOG-1 
SET STEP NOSOURCE " ' 

SET TRACE %LINE 30 
SET BREAK %LINE 60 
SHOW TRACE 

Itracepoint at PROG4ULINE 30 
GO 

Itrace at PROG4\%LINE 30 
[break at PR0G4\%LINE 60 


he DBG> prompt is not recorded, and the debugger output is commented out 
with exclamation points so the file can be used as a debugger command procedure 
without modification. Thus, if a lengthy debugging session is interrupted, you 
can execute the log file as you would any other debugger command procedure. 
Executing the log file restores the debugging session to the point at which it was 
previously terminated. 

To create a debugger log file, use the SET OUTPUT LOG command. By default 
the debugger writes the log to SYS$DISK:[ JDEBUG.LOG. To name a debugger ’ 
log file, use the SET LOG command. You can override any field of the default file 
specification. For example, after you enter the following commands, the debugger 
logs the session to the file [JONES.WORK2JMONITOR.LOG: 

DBG> SET LOG [JONES.WORK2]MONITOR 
DBG> SET OUTPUT LOG 

You might want to enter the SET OUTPUT LOG command in your debugger 
initialization file (see Section 12.2). 
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The SHOW LOG command reports whether the debugger is writing to a log file 
and identifies the current log file. The SHOW OUTPUT command identifies all 
current output options. 

If you are debugging in screen mode, the SET OUTPUT SCREEN_LOG command 
enables you to log the screen contents as the screen is updated. To use this 
command, you must already be logging your debugging session—that is, the 
SET OUTPUT SCREEN_LOG command is valid only after you enter the 
SET OUTPUT LOG command. Using SET OUTPUT SCREEN_LOG is not 
desirable for a long debugging session, because storing screen information in this 
manner results in a large log file. For other techniques on saving screen-mode 
information, see the SAVE and EXTRACT command descriptions. 

To use a log file as a command procedure, first enter the SET OUTPUT VERIFY 
command so that debugger commands are echoed as they are read. 

12.4 Defining Symbols for Commands, Address Expressions, and 
Values 

The DEFINE command enables you to create a symbol for a lengthy or often- 
repeated command sequence or address expression and to store the value of a 
language expression in a symbol. 

You specify the kind of symbol you want to define by the command qualifier you 
use with the DEFINE command (/COMMAND, /ADDRESS, or /VALUE). The 
default qualifier is /ADDRESS. If you plan to enter several DEFINE commands 
with the same qualifier, you can first use the SET DEFINE command to establish 
a new default qualifier (for example, SET DEFINE COMMAND makes the 
DEFINE command behave like DEFINE/COMMAND). The SHOW DEFINE 
command identifies the default qualifier currently in effect. 

Use the SHOW SYMBOL/DEFINED command to identify symbols you have 
defined with the DEFINE command. Note that the SHOW SYMBOL command 
without the /DEFINED qualifier identifies only the symbols that are defined in 
your program, such as the names of routines and variables. 

Use the DELETE command to DELETE symbol definitions created with the 
DEFINE command. 

When defining a symbol within a command procedure, use the /LOCAL qualifier 
to confine the symbol definition to that command procedure. 

12.4.1 Defining Symbols for Commands 

Use the DEFINE/COMMAND command to equate one or more command strings 
to a shorter symbol. The basic syntax is shown in the following example. 

DBG> DEFINE/COMMAND SB = "SET BREAK" 

DBG> SB PARSER 

In the example, the DEFINE/COMMAND command equates the symbol SB 
to the string SET BREAK (note the use of the quotation marks to delimit the 
command string). When the command line SB PARSER is executed, the debugger 
substitutes the string SET BREAK for the symbol SB and then executes the SET 
BREAK command. 
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Additional Convenience Features 
for Commands, Address Expressions, and Values 


lie following example, the DEFINE/COMMAND command equates the symbol 

C ° nsisting of the SH0W BREAK command followed by the 
bHUW 1RACE command (use semicolons to separate multiple command strings): 

DBG> DEFINE/COMMAND BT = "SHOW BREAK;SHOW TRACE" 

The SHOW SYMBOL/DEFINED command identifies the symbol BT as follows: 

DBG> SHOW SYM/DEFINED BT 
defined BT 

bound to: "SHOW BREAK;SHOW TRACE" 
was defined /command 

DBG> 

To define complex commands, you might need to use command procedures with 
parameters (see Section 12.1.2 for information about passing parameters to 
command procedures). For example: 


DBG> DEFINE/COMMAND DUMP = "@DUMP PROG2.COM" 

12.4.2 Defining Symbols for Address Expressions 

Use the DEFINE/ADDRESS command to equate an address expression to a 
symbol. /ADDRESS is the default qualifier for the DEFINE command, but it is 
used in the following examples for emphasis. 

exam P le ’ the s y mbo1 B1 is equated to the address of line 378; the 
bilil BREAK B1 command then sets a breakpoint on line 378: 

DBG> DEFINE/ADDRESS B1 = %LINE 378 
DBG> SET BREAK B1 


The DEFINE/ADDRESS command is useful when you need to specify a long path 
name repeatedly to reference the name of a variable or routine that is defined 

ti T T es - In the next example, the symbol UX is equated to the path name 
SCREEN_IO \ UPDATE \ X; the abbreviated command line EXAMINE UX can 
then be used to obtain the value of X in routine UPDATE of module SCREEN_IO: 


DBG> DEFINE UX = SCREEN IO\UPDATE\X 
DBG> EXAMINE UX 


12.4.3 Defining Symbols for Values 

Use the DEFINE/VALUE command to equate the current value of a language 
expression to a symbol (the current value is the value at the time the 
DEFINE/VALUE command was entered). 


The following example shows how you can use the DEFINE/VALUE command to 
count the number of calls to a routine: 

DBG> DEFINE/VALUE COUNT = 0 

DBG> SET TRACE/SILENT ROUT DO (DEFINE/VALUE COUNT = COUNT + 1) 


DBG> EVALUATE COUNT 
14 

DBG> 
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12.4 Defining Symbols for Commands, Address Expressions, and Values 


In the example, the first DEFINE/VALUE command initializes the value of the 
symbol COUNT to 0. The SET TRACE command sets a silent tracepoint on 
routine ROUT and (through the DO clause) increments the value of COUNT by 1 
every time ROUT is called. After execution is resumed and eventually suspended, 
the EVALUATE command obtains the current value of COUNT (the number of 
times that ROUT was called). 


12.5 


Assigning Commands to Function Keys 

To facilitate entering commonly used commands, the function keys on the keypad 
have predefined debugger functions that are established when you start the 
debugger. These predefined functions are identified in Appendix A. You can 
modify the functions of the keypad keys to suit your individual needs. If you have 
a VT200- or VT300-series terminal or a workstation, you can also bind commands 
to the additional function keys on the LK201 keyboard. 


The debugger commands DEFINE/KEY, SHOW KEY, and DELETE/KEY enable 
you to assign, identify, and delete key definitions, respectively. Before you can 
use this feature, keypad mode must be enabled with the SET MODE KEYPAD 
command (keypad mode is enabled by default). Keypad mode also enables you to 
use the predefined functions of the keypad keys. 


To use the keypad keys to enter numbers rather than debugger commands, enter 
the SET MODE NOKEYPAD command. 


12.5.1 Basic Conventions 

The debugger DEFINE/KEY command, which is similar to the DCL command 
DEFINE/KEY, enables you to assign a string to a function key. In the following 
example, the DEFINE/KEY command defines KP7 (keypad key 7) to enter and 
execute the SHOW MODULE * command: 

DBG> DEFINE/KEY/TERMINATE KP7 "SHOW MODULE *" 

%DEBUG-I-DEFKEY, DEFAULT key KP7 has been defined 
DBG> 

KP7 is the key name that you must use with the commands DEFINE/KEY, 
SHOW KEY, and DELETE/KEY. The valid key names that you can use with 
these commands for VT52 and VTlOO-series terminals and for LK201 keyboards 
are listed in the Key command description in online help. 

In the previous example, the /TERMINATE qualifier indicates that pressing KP7 
executes the command. You do not have to press Return after pressing KP7. 

You can assign any number of definitions to the same function key as long as each 
definition is associated with a different state. The predefined states (DEFAULT, 
GOLD, BLUE, and so on) are identified in Appendix A. In the preceding example, 
the informational message indicates that KP7 has been defined for the DEFAULT 
state (which is the default key state). 

You can enter key definitions in a debugger initialization file (see Section 12.2) so 
that these definitions are available whenever you start the debugger. 


To display a key definition in the current state, enter the SHOW KEY command. 
For example: 


DBG> SHOW KEY KP7 
DEFAULT keypad definitions: 

KP7 = "SHOW MODULE *" (echo,terminate,nolock) 
DBG> 
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To display a key definition m a state other than the current state, specify that 
state with the /STATE qualifier when entering the SHOW KEY command To see 
all key definitions in the current state, enter the SHOW KEY/ALL command. 

To delete a key definition, use the DELETE/KEY command. To delete a key 

m ..^ stat ® other than the current state, specify that state with the 
/BlArE qualifier. For example: 

DBG> DELETE/KEY/STATE=GOLD KP7 
•sDEBUG-I-DELKEY, GOLD key KP7 has been deleted 
DBG> 

12.5.2 Advanced Techniques 

This section shows more advanced techniques for defining keys, particularly 
techniques related to the use of state keys. 

udu A°U 0 r^fT^ 0mmand line assigns the unterminated command string "SET 
BREAK %LINE" to KP9, for the BLUE state: 

DBG> DEFINE/KEY/IF_STATE=BLUE KP9 "SET BREAK %LINE" 

D?TT^ r ? defined DEFAULT ke y state is established by default. The predefined 
BLUE key state is established by pressing the PF4 key. Enter the command 
line assigned in the preceding example (SET BREAK %LINE . . . ) by pressing 
PF4, pressing KP9, entering a line number, and then pressing the Return key to 
terminate and process the command line. 

The SET KEY command enables you to change the default state for key 
definitions. For example, after entering the SET KEY/STATE=BLUE command 
you donotneedtopress PF4 to enter the command line in the previous example. 
Also, the SHOW KEY command will show key definitions in the BLUE state by 

default, and the DELETE/KEY command will delete key definitions in the BLUE 
state by default. 

You can create additional key states. For example: 

DBG> SET KEY/STATE=DEFAULT 

DBG> DEFINE/KEY/SET_STATE=RED/LOCK STATE F12 "" 

In this example, the SET KEY command establishes DEFAULT as the current 
state. The DEFINE/KEY command makes F12 (LK201 keyboard) a state key. As 
a result pressing F12 while in the DEFAULT state causes the current state to 
become RED. The key definition is not terminated and has no other effect (a null 
string is assigned to F12). After pressing F12, you can enter RED commands by 
pressing keys that have definitions associated with the RED state. 


12.6 Using Control Structures to Enter Commands 


The FOR, IF, REPEAT, and WHILE commands enable you to create looping and 

PY n me n A a i C ° nSt T tS f ° r entering debugger commands. The associated command 
EXITLOOP is used to exit a FOR, REPEAT, or WHILE loop. The following 
sections describe these commands. 

See Section 8.1.5 and Section 13.3.2.2 for information about evaluating language 
expressions. 
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12.6.1 FOR Command 

The FOR command executes a sequence of commands while incrementing a 
variable a specified number of times. It has the following syntax: 

FOR name=expression1 TO expression2[ BY expression3\ DO (command^, ... ]) 

For example, the following command line sets up a loop that initializes the first 
10 elements of an array to 0: 

DBG> FOR I = 1 TO 10 DO (DEPOSIT A(I) = 0) 

12.6.2 IF Command 

The IF command executes a sequence of commands if a language expression 
(Boolean expression) is evaluated as true. It has the following syntax. 

IF boolean-expression THEN (command[\ ... ]) [ELSE (command, ...])] 

The following FORTRAN example sets up a condition that issues the command 
EXAMINE X2 if XI is not equal to -9.9, and issues the command EXAMINE Y1 

otherwise: 

DBG> IF XI .NE. -9.9 THEN (EXAMINE X2) ELSE (EXAMINE Yl) 

The following Pascal example combines a FOR loop and a condition test. The 
STEP command is issued if XI is not equal to -9.9. The test is made four times: 

DBG> FOR COUNT = 1 TO 4 DO (IF XI <> -9.9 THEN (STEP)) 

12.6.3 REPEAT Command 

The REPEAT command executes a sequence of commands a specified number of 
times. It has the following syntax: 

REPEAT language-expression DO ( command [; .. . ]) 

For example, the following command line sets up a loop that issues a sequence of 
two commands (EXAMINE Y then STEP) 10 times: 

DBG> REPEAT 10 DO (EXAMINE Y; STEP) 

12.6.4 WHILE Command 

The WHILE command executes a sequence of commands while the language 
expression (Boolean expression) you have specified evaluates as true. It has the 
following syntax: 

WHILE boolean-expression DO ( command [; ... ]) 

The following Pascal example sets up a loop that repetitively tests XI and X2 and 
issues the two commands EXAMINE X2 and STEP if X2 is less than XI: 

DBG> WHILE X2 < XI DO (EX X2;STEP) 

12.6.5 EXITLOOP Command 

The EXITLOOP command exits one or more enclosing FOR, REPEAT, or WHILE 
loops. It has the following syntax: 

EXITLOOP [n] 

The integer n specifies the number of nested loops to exit from. 
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12.7 


The following Pascal example sets up an endless loop that issues a STEP 
command with each iteration. After each step, the value of X is tested. If X is 
greater than 3, the EXITLOOP command terminates the loop. 


DBG> WHILE TRUE DO (STEP; IF X > 3 THEN EXITLOOP) 

Calling Routines Independently of Program Execution 

The CALL command enables you to execute a routine independently of the 
normal execution of your program. It is one of the four debugger commands that 
you can use to execute your program (the others are GO, STEP, and EXIT). 

The CALL command executes a routine whether or not your program actually 
me udes a call to that routine, as long as the routine was linked with your 
program. Thus, you can use the CALL command to execute routines for 
any purpose (for example, to debug a routine out of the context of program 
execution, call a run-time library procedure, call a routine that dumps debugging 
information, and so on). 66 6 


You can debug unrelated routines by linking them with a dummy main program 
that has a transfer address, and then using the CALL command to execute them. 

The following example shows how you can use the CALL command to display 
some process statistics without having to include the necessary code in your 
program The example consists of calls to run-time library routines that initialize 

f T T rQmS Ew! R) a ^ d display the ela Psed time and various statistics 
(LIB$SHOW_TIMER). (Note that the presence of the debugger affects the timings 
and counts.) 6 


DBG> SET MODULE SHARE$LIBRTL © 

DBG> CALL LIB$INIT_TIMER © 
value returned is 1 © 

DBG> [ enter various debugger commands ] 


DBG> CALL LIB$SHOW_TIMER © 

ELAPSED: 0 00:00:21.65 CPU: 0:14:00.21 BUFIO: 16 DIRIO: 0 FAULTS* 3 

value returned is 1 

DBG> 

The comments that follow refer to the callouts in the previous example: 

O The routines LIB$INIT_TIMER and LIB$SHOW_TIMER are in the shareable 
image LIBRTL. This image must be set by setting its module, because 
only its universal symbols are accessible during a debugging session (see 
Section 9.4.2.3). 

© This CALL command executes the routine LIB$INIT_TIMER. 

0 The value returned message indicates the value returned in register RO after 
the CALL command has been executed. 

By convention, after a called routine has executed, register RO contains the 
function return value (if the routine is a function) or the procedure completion 
status (if the routine is a procedure that returns a status value). If a called 
procedure does not return a status value or function value, the value in RO 
might be meaningless, and the value returned message can be ignored. 

© This CALL command executes the routine LIB$SHOW_TIMER. 
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12.7 Calling Routines Independently of Program Execution 


The following example shows how to call LIB$SHOW_VM (also m LIBRTL) to 
display memory statistics. Again, note that the presence of the debugger a ec s 

the counts: 


DBG> SET MODULE SHARE$LIBRTL 
DBG> CALL LIB$SHOW_VM 

1785 calls to LIB$GET_VM, 284 calls to LIB$FREE_VM, 

122216 bytes still allocated value returned is 1 
DBG> 

You can pass parameters to routines with the CALL command. See the CALL 
command description for details and examples. 
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Debugging Special Cases 


This chapter presents debugging techniques for special cases that are not covered 
elsewhere in this manual: 

• Optimized code 

• Screen-oriented programs 

• Multilanguage programs 

• Stack corruption 

• Exceptions and condition handlers 

• Exit handlers 

• AST-driven programs 

• Translated images 

13.1 Debugging Optimized Code 

By default, many compilers optimize the code they produce so that the program 
executes faster. With optimization, invariant expressions are removed from DO 
loops so that they are evaluated only once at run time, some memory locations 
might be allocated to different variables at different points in the program, and 
some variables might be eliminated so that you no longer have access to them 
while debugging. 

The net result is that the code that is executing as you debug might not match 
the source code displayed in a screen-mode source display (see Section 11.2.1) or 
in a source listing file. 

To avoid the problems of debugging optimized code, many compilers allow you 
to specify the /NOOPTIMIZE (or equivalent) command qualifier at compile 
time. Specifying this qualifier inhibits most compiler optimization and thereby 
reduces discrepancies between the source code and executable code caused by 
optimization. 

If this option is not available to you, or if you have a definite need to debug 
optimized code, read this section. It describes the techniques for debugging 
optimized code and gives some typical examples of optimized code to show the 
potential causes of confusion. It also describes some features you can use to 
reduce the confusion inherent in debugging optimized code. 

In order to take advantage of the features that improve the ability to debug 
optimized code, you need an up-to-date version of your language compiler. For 
definitive information about the necessary version of your compiler, please see 
your compiler release notes or other compiler documentation. 

Note that about one-third more disk space is needed for debugging optimized 
code, to accommodate the increased image size. 


13-1 




Debugging Special Cases 
13.1 Debugging Optimized Code 


When debugging optimized code, use a screen-mode instruction display, such 
as the predefined display INST, to show the decoded instruction stream of your 
program (see Section 11.2.4). An instruction display shows the exact code that is 
executing. 

In screen mode, pressing KP7 places the SRC and INST displays side by 
side for easy comparison. Alternatively, you can inspect a compiler-generated 
machine-code listing. 

In addition, to execute the program at the instruction level and examine 
instructions, use the techniques described in Section 8.3. 

Using these methods, you should be able to determine what is happening at 
the executable code level and be able to resolve the discrepancy between source 
display and program behavior. 

13.1.1 Eliminated Variables 

A compiler might optimize code by eliminating variables, either permanently 
or temporarily at various points during execution. For example, if you try to 
examine a variable X that no longer is accessible because of optimization, the 
debugger might display one of the following messages. 

%DEBUG-W-UNALLOCATED, entity X was not allocated in memory 
(was optimized away) 

%DEBUG-W-NOVALATPC, entity X does not have a value at the 
current PC 

The following Pascal example shows how this could happen. 

PROGRAM DOC(OUTPUT); 

VAR 

X, Y: INTEGER; 

BEGIN 

X := 5; 

Y := 2; 

WRITELN(X*Y); 

END. 

If you compile this program with the /NOOPTIMIZE (or equivalent) qualifier, you 
obtain the following (normal) behavior when debugging: 


13-2 




Debugging Special Cases 
13.1 Debugging Optimized Code 


$ PASCAL/DEBUG/NOOPTIMIZE DOC 
$ LINK/DEBUG DOC 
$ DEBUG/KEEP 


DBG> RUN DOC 


DBG> STEP 

stepped to DOCULINE 5 
5: X := 5; 

DBG> STEP 

stepped to DOCULINE 6 

6: Y := 2; 

DBG> STEP 

stepped to D0C\%LINE 7 

7: WRITELN(X*Y); 

DBG> EXAMINE X,Y 
D0C\X: 5 
D0C\Y: 2 
DBG> 

If you compile the program with the /OPTIMIZE (or equivalent) qualifier, because 
the values of X and Y are not changed after the initial assignment, the compiler 
calculates X*Y, stores that value (10), and does not allocate storage for X or Y. 
Therefore, after you start debugging, a STEP command takes you directly to line 
7 rather than line 5. Moreover, you cannot examine X or Y: 

$ PASCAL/DEBUG/OPTIMIZE DOC 
$ LINK/DEBUG DOC 
$ DEBUG/KEEP 


DBG> RUN DOC 




DBG> EXAMINE X,Y 

oDEBUG-W-UNALLOCATED, entity X was not allocated in memory 
(was optimized away) 

DBG> STEP 

stepped to DOCULINE 7 

7: WRITELN(X*Y); 

DBG> 

On VAX processors, to see what values are being used in your optimized program 
use the EXAMINE/OPERAND ,%PC command to display the machine code at the’ 
current PC value, including the values and symbolization of all of the operands. 
For example, the following lines show the optimized code when the PC value is at 
the WRITELN statement: 

DBG> STEP 

stepped to DOCULINE 7 

7: WRITELN(X*Y); 

DBG> EXAMINE/OPERAND UPC 
DOCULINE 7: PUSHL S A #10 

DBG> 
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In contrast, the following lines show the unoptimized code at the WRITELN 
statement: 

DBG> STEP 

stepped to DOC\%LINE 7 

7: WRITELN(X*Y); 

DBG> EXAMINE/OPERAND .%PC 

D0C\%LINE 7: MOVL S A #10,B A -4(FP) 

B A -4(FP) 2146279292 contains 62914576 

DBG> ♦ 

13.1.2 Changes in Coding Order 

Several methods of optimizing consist of performing operations in a sequence 
different from the sequence specified in the source code. Sometimes code is 
eliminated altogether. 

As a result, the source code displayed by the debugger does not correspond exactly 
to the actual code being executed. 

The following example depicts a segment of source code from a FORTRAN 
program as it might appear on a compiler listing or in a screen-mode source 
display. This code segment sets the first ten elements of array A to the value 1/X. 

Line Source Code 


5 DO 100 1=1,10 

6 A(I) = 1/X 

7 100 CONTINUE 

Optimization may produce the following scenario: As the compiler processes the 
source program, it determines that the reciprocal of X need only be computed 
once, not 10 times as the source code specifies, because the value of X never 
changes in the DO loop. The compiler thus may generate optimized code 
equivalent to the following code segment: 

Line Optimized Code Equivalent 


5 TEMP = 1/X 
DO 100 1=1,10 

6 A (I) = TEMP 

7 100 CONTINUE 

Depending on the compiler implementation, the moved code may be associated 
with the first line of the loop (common on VAX systems) or may retain its original 
line number (common on Alpha systems). 

If a discrepancy occurs, it is not obvious from looking at the displayed source 
line. Furthermore, if the computation of 1/X were to fail because X is 0, it would 
appear from inspecting the source display that a division by 0 had occurred on a 
source line that contains no division at all. 

This kind of apparent mismatch between source code and executable code should 
be expected from time to time when you debug optimized programs. It can be 
caused not only by code motions out of loops, as in the previous example, but by a 
number of other optimization methods as well. 
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Alpha 


13.1.3 Semantic Stepping (Alpha Only) 

Semantic stepping (available only on Alpha systems) makes stepping through 
optimized eode less confusing. The semantic-stepping mode complements the 
traditional step-by-line and step-by-instruction modes. There are two commands 
lor semantic stepping: SET STEP SEMANTIC_EVENT and STEP/SEMANTIC 
EVENT. 


Semantic Events 

One problem of stepping through optimized code is that the apparent source 
program location "bounces'' back and forth with the same line often appearing 
again and again. Indeed, sometimes the forward progress in STEP LINE mode 
averages barely more than one instruction per STEP command. 


This problem is addressed through annotating instructions that are semantic 
events. Semantic events are important for two reasons: 

They represent the points in the program where the effects of the program 
actually happen. 


These effects tend to happen in an order that remains close to the source 
order of events in the program. 


A semantic event is one of the following: 

• Data event — An assignment to a user variable 

• Control event — A control flow decision, with a conditional or unconditional 
transfer of control, other than a call 

• Call event A call (to a routine that is not stepped over) or a return from a 
call 


It is important to understand that not every assignment, transfer of control, or 
call is necessarily a semantic event. The major exceptions are as follows: 

When two instructions are required to assign to a complex or X_floating value, 
only the first instruction is treated as a semantic event. 

• When there are multiple branches that are part of a single higher-level 
construct, such as a decision tree of branches that implement a case or select 
construct, then only the first is treated as a semantic event. 

When a call is made to a routine that is a compiler-specific helper routine 
such as a call to OTS$MOVE, which handles certain kinds of string or storage 
copy operations, the call is not considered a semantic event. This means that 
control will not stop at the call. 

To step into such a routine, you must do either of the following: 

— Set a breakpoint at the routine entry point, 

- Use a series of STEP/INSTRUCTION commands to reach the call of 
interest and then use STEP/INSTRUCTION/INTO to enter the called 
routine. 

When there is more than one semantic event in a row with the same line 
number, then only the first is used. 

SET STEP SEMANTIC_EVENT Command 

The SET STEP SEMANTIC_EVENT command establishes the default stepping 
mode as semantic. 
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STEP/SEMANTIC_EVENT Command 

STEP/SEMANTIC_EVENT, or simply STEP when semantic mode is in effect, 
causes a breakpoint to be set at the next semantic event, whether an assignment, 
a transfer of control, or a call. Execution proceeds to that next event. Parts ot 
any number of different lines/statements may be executed along the way without 
interfering with progress. When the semantic event is reached (that is, when the 
instruction associated with that event is reached but not yet executed), execution 
is suspended (similar to reaching the next line when STEP/LINE is used). 

Example of Semantic Stepping 

The comments in the following C program, doct2, point out some considerations 
for optimization: 

♦include <stdio.h> 

♦include <stdlib.h> 

int main(unsigned argc, char **argv) { 
int w, x, y, z=0; 

x = atoi(argv[l]) ; 
printf("%d\n", x); 

x = 5; 
y = x; 

if (y > 2) { 

printf("y > 2"); 

} 

else { 

printf("y <= 2"); 

} 

if (z) { 

printf ("z"); 

} 

else { 

printf("not z"); 

} 

printf("\n"); 

} 

Contrast the following two examples, which show stepping by line and stepping 
by semantic event through the optimized doct2 program: 

• Stepping by line: 

$ doct2:=$sys$disk:[]doct2 
$ doct2 6 

Debugger Banner and Version Number 


/* always true */ 


/* always false */ 
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%DEBUG-I-INITIAL, Language: C, Module: D0CT2 
%DEBUG-I-NOTATMAIN, Type GO to reach MAIN program 
DBG> go 

break at routine D0CT2\main 
654: x = atoi(argv[l]); 

DBG> step 

stepped to D0CT2\main\%LINE 651 

651: int main(unsigned argc, char **arqv) { 

DBG> step 

stepped to D0CT2\main\%LINE 654 
654: x = atoi(argv[l]); 

DBG> step 

stepped to D0CT2\main\%LINE 651 

651: int main(unsigned argc, char **arqv) { 

DBG> step 

stepped to D0CT2\main\%LINE 654 
654: x = atoi(argv[l]); 

DBG> step 

stepped to D0CT2\main\%LINE 655 
655: printf("%d\n", x); 

DBG> step 

stepped to D0CT2\main\%LINE 654 
654: x = atoi(argv[l]); 

DBG> step 

stepped to D0CT2\main\%LINE 655 
655: printf("%d\n", x); 

DBG> step 
6 

stepped to D0CT2\main\%LINE 661 
661: printf("y > 2"); 

DBG> step 
Y > 2 

stepped to D0CT2\main\%LINE 671 
671: printf("not z"); 

DBG> step 
not z 

stepped to D0CT2\main\%LINE 674 
674: printf("\n"); 

DBG> step 

stepped to D0CT2\main\%LINE 675 
675: } 

DBG> step 

%DEBUG-I-EXITSTATUS, is 'ISYSTEM-S-NORMAL, normal successful completion' 
DBG> 

• Stepping by semantic event: 

$ doct2:=$sys$disk:[]doct2 
$ doct2 6 

Debugger Banner and Version Number 
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%DEBUG-I-INITIAL, Language: C, Module: D0CT2 
%DEBUG-I-NOTATMAIN, Type GO to reach MAIN program 
DBG> set step semantic_event 
DBG> go 

break at routine D0CT2\main 
654: x = atoi(argv[1]); 

DBG> step 

stepped to D0CT2\inain\%LINE 654+8 
654: x = atoi(argv[1]); 

DBG> step 

stepped to D0CT2\niain\%LINE 655+12 
655: printf("%d\n", x) ; 

DBG> step 
6 

stepped to D0CT2\main\%LINE 661+16 
661: printf ("y > 2"); 

DBG> step 
y > 2 

stepped to D0CT2\main\%LINE 671+16 
671: printf("not z"); 

DBG> step 
not z 

stepped to D0CT2\main\%LINE 674+16 
674: printf("\n"); 

DBG> step 

stepped to D0CT2\inain\%LINE 675+24 
675: } 

DBG> step 

stepped to DOCT2\_main+104 

DBG> step _ , . , 

%DEBUG-I-EXITSTATUS, is '%SYSTEM-S-NORMAL, normal successful completion 

DBG> 

Notice that the semantic stepping behavior is much smoother and more 
straightforward than the stepping-by-line example. Further, semantic stepping 
results in stopping at significant points of the program. In general, semantic 
stepping significantly reduces or eliminates the confusion of bouncing around 
the code nonsequentially, which characteristically happens with stepping by line 
through optimized code. Although some reordering of the source program may be 
done to take advantage of better execution characteristics, generally the flow is 
from top to bottom. 

The granularity of stepping is different between stepping by line and stepping 
semantically. Sometimes it is greater, sometimes smaller. For example, a 
statement that would by its semantic nature constitute a semantic event will 
not show up with semantic stepping if it has been optimized away. Thus, the 
semantic region will span across several lines, skipping the line that has been 
optimized away. ♦ 

13.1.4 Use of Registers 

A compiler might determine that the value of an expression does not change 
between two given occurrences and might save the value in a register. In such 
cases, the compiler does not recompute the value for the next occurrence, but 
assumes the value saved in the register is valid. 

If, while debugging a program, you use the DEPOSIT command to change the 
value of the variable in the expression, the corresponding value stored in the 
register might not be changed. Thus, when execution continues, the value in the 
register might be used instead of the changed value in the expression, which will 
cause unexpected results. 
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In addition, when the value of a nonstatic variable (see Section 7 4 3) is held in 
a register its value in memory is generally invalid; therefore, a spurious value 
might be displayed if you enter the EXAMINE command for a variable under 
these circumstances. 

13.1.5 Use of Condition Codes (VAX Only) 

tiilp On VAX processors, one optimization technique takes advantage of the way in 
which the VAX processor condition codes are set. For example, consider the 
following Pascal source code: 

X := X + 2.5; 

IF X < 0 
THEN 


Rather than test the new value of X to determine whether to branch, the 
optimized code bases its decision on the condition code setting after 2.5 is added 

; S ’ if , y0U . attem P t t0 set a breakpoint on the IF statement and deposit 
a different value into X, you do not achieve the intended result because the 
condition codes no longer reflect the value of X. In other words, the decision to 
branch is being made without regard to the deposited value of the variable. 


Again, you can use the EXAMINE/OPERAND ,%PC command to determine the 
correct location for depositing so as to achieve the results you expect. ♦ 

13.1.6 Split-Lifetime Variables 


Alpha 


In compiling with optimization, the compiler sometimes performs split-lifetime 
analysis on a variable, "splitting" it into several independent subvariables that 
can be independently allocated. The effect is that the original variable can be 
thought to reside in different locations at different points in time - sometimes in 
a register, sometimes in memory, and sometimes nowhere. It is even possible for 
the different subvariables to be simultaneously active. 


In response to the EXAMINE command, the debugger tells you at which locations 
in the program the variable was defined. When the variable has an inappropriate 
value, this location information can help you determine where the value of the 
variable was assigned. (The /DEFINITIONS qualifier enables you to specify more 
or fewer than the default five locations.) ♦ 


Split-lifetime analysis applies only to scalar variables and parameters. It does 
not apply to arrays, records, structures, or other aggregates. 

Examples of Split-Lifetime Processing 

The following examples illustrate the use of split-lifetime processing. For the 

first example, a small C program, the numbers in the left column are listing line 
numbers. b 
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385 doct8 () { 

386 

387 int i, j, k; 

388 

389 i = 1; 

390 j = 2; 

391 k = 3; 

392 

393 if (foo(i)) { 

394 j = 17; 

395 } 

396 else { 

397 k = 18; 

398 } 

399 

400 printf("%d, %d, %d\n", i, j, k); 

401 

402 } 

When compiled, linked, and executed for debugging, the optimized program 
results in this dialogue; 

$ run doct8 


DBG> step/into 

stepped to DOCT8\doct8\%LINE 391 
391: k = 3; 

DBG> examine i 

%W, entity 'i' was not allocated in memory (was optimized away) 

DBG> examine j 

%W, entity 'j' does not have a value at the current PC 
DBG> examine k 

%W, entity 'k' does not have a value at the current PC 

Note the difference in the message for the variable i compared to j or k. The 
variable i was not allocated in memory (registers, core, or otherwise) at all, so 
there is no point in ever trying to examine its value again. By contrast, j and k 
do not have a value "at the current PC" here; somewhere later in the program 
they will. 

Stepping one more line results in this: 

DBG> step 

stepped to DOCT8\doct8\%LINE 385 
385: doct8 () { 

This looks like a step backward — a common phenomenon in optimized 
(scheduled) code. (This problem is dealt with by "semantic stepping mode," 
discussed in Section 13.1.2.) Continuing to step results in this. 
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DBG> step 5 

stepped to DOCT8\doct8\%LINE 391 
391: k = 3; 

DBG> examine k 

oW, entity k does not have a value at the current PC 
DBG> step 

stepped to DOCT8\doct8\%LINE 393 
393: if (foo(i)) { 

DBG> examine j 

•sW, entity 'j' does not have a value at the current PC 
DBG> examine k 
DOCT8\doct8\k: 3 

value defined at DOCT8\doct8\%LINE 391 

Here j is still undefined, but k now has a value, namely 3. That value was 
assigned at line 391. 

Recall from the source thatj was assigned a value before k (at line 390), but that 
has yet to show up. Again, this is common with optimized (scheduled) code. 

DBG> step 

stepped to DOCT8\doct8\%LINE 390 
390: j = 2; 

Here the value of j appears. Thus: 

DBG> examine j 

oW, entity j does not have a value at the current PC 
DBG> step 

stepped to DOCT8\doct8\%LINE 393 

393: if (foo(i)) { 

DBG> examine j 
DOCT8\doct8\j: 2 

value defined at DOCT8\doct8\%LINE 390 

Skipping ahead to the print statement at line 400, examine j again. 

DBG> set break %line 400 
DBG> g 

break at DOCT8\doct8\%LINE 400 

400: printf("%d, %d, %d\n", i, j, k); 

DBG> examine j 
DOCT8\doct8\j: 2 

value defined at DOCT8\doct8\%LINE 390 
value defined at DOCT8\doct8\%LINE 394 

Here there is more than one definition location given for j. Which applies depends 
on which path was taken in the IF clause. If a variable has an apparently 
inappropriate value, this mechanism provides a means to take a closer look at 
those places, and only those, where that value might have come from. 

You can use the SHOW SYMBOL/ADDRESS command to display the split¬ 
lifetime information for a symbol, as in the following example: 
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Alpha 


DBG> show symbol/address j 
data DOCT8\doct8\j 

between PC 131128 and 131140 

PC definition locations are at: 131124 
address: %R3 

between PC 131144 and 131148 

PC definition locations are at: 131140 
address: %R3 

between PC 131152 and 131156 

PC definition locations are at: 131124 
address: %R3 

between PC 131160 and 131208 

PC definition locations are at: 131124, 131140 
address: %R3 

The variable j has four lifetime segments. The PC addresses are the result of 
linking the image, and the comments relate them to line numbers in the source 

program. 

• The first segment starts at the assignment of 2 to j and extends through the 
test to just before the assignment of 17 to j. 

• The second segment starts at the assignment of 17 to j and extends up to the 
ELSE part of the IF statement. 

• The third segment corresponds to the ELSE clause. There is no assignment 
to j in this range of PCs. Note that the definition ofj that applies here is from 
the first segment. 

• The fourth segment starts at the join point following the IF clause and 
extends to the end of the program. The definition ofj comes from either line 
390 or line 394 depending on which path was taken through the IF statement. 

There is one major conceptual difference between the split-lifetime support on 
OpenVMS Alpha systems and what is available on OpenVMS VAX systems. On 
Alpha the debugger tracks and reports which assignments and definitions might 
have provided the displayed value of a variable. This additional information can 
help you cope with some of the effects of code motion and other optimizations — 
effects that cause a variable to have a value coming from an unexpected place in 
the program. 

EXAMINE/DEFINITIONS Command 

For a split-lifetime variable, the EXAMINE command not only displays the 
value of the active lifetime, it also displays the lifetime’s definition points. The 
definition points are places where the lifetime could have received an initial value 
(if there is only one definition point, then that is the only place.) 

There is more than one definition point if a lifetime’s initial value can come from 
more than one place. In the previous example when the program is suspended at 
the printf, examining / results in the following: 


DBG> examine j 
DOCT8\doct8\j: 2 

value defined at DOCT8\doct8\%LINE 390 
value defined at DOCT8\doct8\%LINE 394 

Here, the lifetime of j has two definition points, because the value could have 
come’from either line 390 or line 394, depending on whether or not the expression 
at line 393 was TRUE. 
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By default, up to five definition locations are displayed when the contents of 
a variable are examined. You can specify the number of definition locations to 
display with the /DEFINITIONS=n qualifier, as in the following example: 

DBG> EXAMINE/DEFINITIONS=74 F00 

Note that the minimum abbreviation is /DEFI. 


If you want a default number of definitions other than five, you can use a 
command definition like the following: 

DBG> DEFINE/COMMAND E = "EXAMINE/DEFINITIONS=100" 

If the /DEFINITIONS qualifier is set to 100, and the split-lifetime variable 

e ™ ned has 120 definition points, the debugger displays the 100 as specified 
and then reports: ’ 

there are 20 more definition points ♦ 

13.2 Debugging Screen-Oriented Programs 

The debugger uses the terminal screen for input and output (I/O) during a 
debugging session. If you use a single terminal to debug a screen-oriented 

program that uses most or all of the screen, debugger I/O can overwrite, or can be 
overwritten by, program I/O. 


Using one terminal for both program I/O and debugger I/O is even more 
complicated if you are debugging in screen mode and your screen-oriented 
program calls any Run-Time Library (RTL) Screen Management (SMG$) routines 
Ibis is because the debugger’s screen mode also calls SMG routines. In such 
cases, the debugger and your program share the same SMG pasteboard which 
causes further interference. 


To avoid these problems when debugging a screen-oriented program, use one of 
the following techniques to separate debugger I/O from program I/O: 

If you are at a workstation running VWS, start your debugging session and 
then enter the debugger command SET MODE SEPARATE. It creates a 
separate terminal-emulator window for debugger I/O. Program I/O continues 
to be displayed in the window from which you started the debugger. 

• If you are at a workstation running DECwindows Motif: 

To display the debugger’s DECwindows Motif interface on a separate 
workstation (also running DECwindows Motif), see Section 2.7.3.1. 

To use the debugger’s command interface rather than the DECwindows 
interface ’ see Section 2.7.3.3. It explains how to create a separate 
DECterm window for debugger I/O. The effect is similar to using the 
command SET MODE SEPARATE on a workstation running VWS. 

• If you do not have a workstation, use two terminals—one for program I/O 

and another for debugger I/O. This technique is described in the rest of this 
section. 

Assume that TTD1: is your current terminal from which you plan to start the 
debugger. You want to display debugger I/O on terminal TTD2: so that TTD1- is 
devoted exclusively to program I/O. 
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Follow these steps: 

1. Provide the necessary protection to TTD2: so that you can allocate that 
terminal from TTD1: (see Section 13.2.1). 

The remaining steps are all performed from TTD1:. 


2. Allocate TTD2:. This provides your process on TTD1: with exclusive access to 
TTD2: as follows: 

$ ALLOCATE TTD2: 

3. Assign the debugger logical names DBG$INPUT and DBG$OUTPUT to 
TTD2: as follows: 


4. 


$ DEFINE DBG$INPUT TTD2: 

$ DEFINE DBG$OUTPUT TTD2: 


DBG$INPUT and DBG$OUTPUT specify the debugger input device and 
output device, respectively. By default, these logical names are equated to 
SYS$INPUT and SYS$OUTPUT, respectively. Assigning DBG$1MPUI ana 
DBG$OUTPUT to TTD2: enables you to display debugger commands and 
debugger output on TTD2:. 


Make sure that the terminal type is known to the system. Enter the following 
command: 


$ SHOW DEVICE/FULL TTD2: 

If the device type is unknown, your system manager (or a user with LOG_IO 
or PHY_IO privilege) must make it known to the system as shown in the 
following example. In the example, the terminal is assumed to be a VT200: 

$ SET TERMINAL/PERMANENT/DEVICE=VT200 TTD2: 

5. Run the program to be debugged: 

$ DEBUG/KEEP 


DBG> RUN prog-name 

You can now observe debugger I/O on TTD2: 

6. When finished with the debugging session, deallocate TTD2: as follows (or log 
out): 

$ DEALLOCATE TTD2: 

13.2.1 Setting the Protection to Allocate a Terminal 

On a properly secured system, terminals are protected so that you cannot allocate 
a terminal from another terminal. 

To set the necessary protection, your system manager (or a user with the 
privileges indicated) should follow the steps shown in the following example. 

In the example, TTD1: is your current terminal (from which you plan to start 
the debugger), and TTD2: is the terminal to be allocated so that it can display 

debugger I/O. 

1. If both TTD1: and TTD2: are hardwired to the system, go to step 4. 

If TTD1: and TTD2: are connected to the system over a LAT (local area 
transport), go to step 2. 
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2. Log in to TTD2:. 

3. Enter these commands (you need LOG_IO or PHY_IO privilege): 

$ SET PROCESS/PRIV=LOG_IO 
$ SET TERMINAL/NOHANG/PERMANENT 
$ LOGOUT/NOHANG 

4. Enter one of the following commands (you need OPER privilege): 

$ SET ACL/OBJECT_TYPE=DEVICE/ACL=(IDENT=[PROJ,JONES],ACCESS=READ+WRITE) TTD2• O 

$ SET PR0TECTI0N=W0RLD:RW/DEVICE TTD2: © 

® The Ar>T^ L command lme is preferred because it uses an access control 

rivo'JT the exam P le ’ access is restricted to user identification code 
(UIC) [PROJ,JONES], 

© The SET PROTECTION command line provides world read/write access, 
which allows any user to allocate and perform I/O to TTD2:. 

13.3 Debugging Multilanguage Programs 

The debugger enables you to debug modules whose source code is written in 
different languages within the same debugging session. This section highlights 

some language-specific behavior that you should be aware of to minimize possible 
confusion. ^ 

When debugging in any language, be sure to consult: 

• The debugger’s online help (type HELP Language) 

• The documentation supplied with that language 

13.3.1 Controlling the Current Debugger Language 

When you bring a program under debugger control, the debugger sets the 
current language to that in which the module containing the main program 
(usually the routine containing the image transfer address) is written The 
current language is identified at that point. For example: 

$ DEBUG/KEEP 

Debugger Banner and Version Number 
DBG> RUN prog-name 

-oDEBUG-1-INITIAL, language is PASCAL, module set to FORMS 
DBG> 


The current language setting determines how the debugger parses and interprets 
the names, operators, and expressions you specify in debugger commands, 
including thmgs like the typing of variables, array and record syntax, the default 
radix for integer data, case sensitivity, and so on. The language setting also 
determines how the debugger displays data associated with your program. 

Many programs include modules that are written in languages other than that 
of the mam program. To minimize confusion, by default the debugger language 
remains set to the language of the main program throughout a debugging session 
even if execution is paused within a module written in another language. 

advantage of symbolic debugging with such modules, use the SET 
LANGUAGE command to set the debugging context to that of another language 
b or example, the following command causes the debugger to interpret any 
symbols, expressions, and so on according to the rules of the COBOL langu a ge: 
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DBG> SET LANGUAGE COBOL 


On VAX processors, the SET LANGUAGE command takes the following 
keywords: 


ADA 

BASIC 

BLISS 

C 

C_PLU S_PLUS 

COBOL 

DIBOL 

FORTRAN 

MACRO 

SCAN ♦ 

PASCAL 

PLI 

RPG 

On Alpha processors, the SET 
keywords: 

LANGUAGE command takes the following 

ADA 

AMACRO 

BASIC 

BLISS 

C 

C_PLU S_PLU S COBOL 

Fortran 

MACRO 

MACR064 

PASCAL 

PLI ♦ 


In addition, when debugging a program that is written in an unsupported 
language, you can specify the SET LANGUAGE UNKNOWN command. To 
maximize the usability of the debugger with unsupported languages, the »Ei 
LANGUAGE UNKNOWN command causes the debugger to accept a large set ot 
data formats and operators, including some that might be specific to only a few 
supported languages. The operators and constructs that are recognized when the 
language is set to UNKNOWN are identified in the debugger’s online help (type 
HELP Language). 


13.3.2 Specific Differences Among Languages 

This section lists some of the differences you should keep in mind when debugging 
in various languages. Included are differences that are affected by the SET 
LANGUAGE command and other differences (for example, language-specific 
initialization code and predefined breakpoints). 

This section is not intended to be complete. See the debugger’s online help (type 
HELP Language) and your language documentation for complete details. 


13.3.2.1 Default Radix 

The default radix for entering and displaying integer data is decimal for most 
languages. 




On VAX processors, the exceptions are BLISS and MACRO-32, which have a 
hexadecimal default radix. ♦ 


Alpha 


On Alpha processors, the exceptions are BLISS, MACRO-32, and MACRO 64, 
which have a hexadecimal default radix. ♦ 


Use the SET RADIX command to establish a new default radix. 


13.3.2.2 Evaluating Language Expressions 

Several debugger commands and constructs evaluate language expressions: 

. The EVALUATE, DEPOSIT, IF, FOR, REPEAT, and WHILE commands 

• WHEN clauses, which are used with the SET BREAK, SET TRACE, and SET 
WATCH commands 

When processing these commands, the debugger evaluates language expressions 
in the syntax of the current language and in the current radix as discussed in 
Section 8.1.5. At each execution (not when you enter the command), the debugger 
checks the syntax of any expressions in WHEN or DO clauses, and then evaluates 


them. 
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Note that operators vary widely among different languages. For example, 
the following two commands evaluate equivalent expressions in Pascal and 
FORTRAN, respectively: 

DBG> SET WATCH X WHEN (Y < 5) ! Pascal 

DBG> SET WATCH X WHEN (Y .LT. 5) ! FORTRAN 

Assume that the language is set to PASCAL and you have entered the first 
(Pascal) command. You now step into a FORTRAN routine, set the language to 
FORTRAN, and resume execution. While the language is set to FORTRAN, the 
debugger is not able to evaluate the expression (Y < 5). As a result, it sets an 
unconditional watchpoint and, when the watchpoint is triggered, returns a syntax 
error for the < operator. 

This type of discrepancy can also occur if you use commands that evaluate 
language expressions in debugger command procedures and initialization files. 

When the language is set to BLISS, the debugger processes language expressions 
that contain variable names (or other address expressions) differently than when 
it is set to another language. See Section 8.1.5 for details. 

13.3.2.3 Arrays and Records 

The syntax for denoting array elements and record components (if applicable) 
varies among languages. 

For example, some languages use brackets ([]), and others use parentheses (()) 
to delimit array elements. 

Some languages have zero-based arrays. Some languages have one-based arrays, 
as in the following example: 

DBG> EXAMINE INTEGER_ARRAY 
PR0G2\INTEGER ARRAY 


(1,1) 

27 

(1,2) 

31 

(1,3) 

12 

(2,1) 

15 

(2,2) 

22 

(2,3) 

18 


DBG> 

For some languages (like Pascal and Ada) the specific array declaration 
determines how the array is based. 

13.3.2.4 Case Sensitivity 

Names and language expressions are case sensitive in C. You must specify 
them exactly as they appear in the source code. For example, the following two 
commands are not equivalent when the language is set to C: 

DBG> SET BREAK SCREEN_IO\%LINE 10 
DBG> SET BREAK screen io\%LINE 10 
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13.3.2.5 Initialization Code 

Many programs issue a NOTATMAIN message when a program is brought under 
debugger control. For example: 

$ DEBOG/KEEP 

Debugger Banner and Version Number 
DBG> RUN prog-name 

IDEBUG-I-INITIAL, language is ADA, module set to MONITOR 
IDEBUG-I-NOTATMAIN, type GO to get to start of main program 
DBG> 

The NOTATMAIN message indicates that execution is paused before the 
beginning of the main program. This enables you to execute and check some 
initialization code under debugger control. 

The initialization code is created by the compiler and is placed in a special 
PSECT named LIB$INITIALIZE. For example, in the case of an Ada package, the 
initialization code belongs to the package body (which might contain statements 
to initialize variables, and so on). In the case of a FORTRAN program, the 
initialization code declares the handler that is needed if you specify the 
/CHECK=UNDERFLOW or /CHECK=ALL qualifier. 

The NOTATMAIN message indicates that, if you do not want to debug the 
initialization code, you can execute immediately to the beginning of the main 
program by entering a GO command. You are then at the same point as when 
you start debugging any other program. Entering the GO command again starts 
program execution. 

13.3.2.6 Predefined Breakpoints 

If your program is a tasking program, two breakpoints that are associated with 
tasking exception events are automatically established when the program is 
brought under debugger control. These breakpoints are not affected by a SET 
LANGUAGE command. They are established automatically during debugger 
initialization when appropriate run-time libraries are present. 

To identify these predefined breakpoints, enter the SHOW BREAK command. For 
example: 

DBG> SHOW BREAK ^ , 

Predefined breakpoint on ADA event "EXCEPTION_TERMINATED for any value 
Predefined breakpoint on ADA event "DEPENDENTS_EXCEPTION" for any value 
DBG> 

13.3.2.7 STEP/OVER Command and Fortran 

On VAX systems, the STEP/OVER command may result in stepping into, not 
%i2iP overj Fortran Run-Time Library (RTL) routines. If you are debugging a DEC 

Fortran program, and the debugger encounters a Fortran I/O operation such as 
READ WRITE, or PRINT, the Fortran compiler calls a Fortran RTL routine to 
complete the I/O operation. When you issue a STEP command at the call to the 
RTL routine, the debugger steps into, rather than over, the routine and issues the 
following error message: 

%DEBUG-W-NOSCRLIN, no source line for address nnnnnnnn 

The reason is that the debugger steps over routines by searching for a RET 
instruction to be executed; however, the Fortran compiler deallocates temporary 
strings used in Fortran RTL I/O routines from the stack in a nonstandard way, 
without an explicit RET instruction. 
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To recover from the error message, issue several STEP commands to return 
the session to the expected line of code. To prevent recurrence of the problem, 
modify your program to include a temporary variable that stores the results of 
the function prior to the I/O statement. For example: 

CHARACTER*23 cl, c2 

WRITE^*) 1 ! cl is the temporary variable 

END 

C 

CHARACTER*23 FUNCTION c2() 
c2 = 'ABCDEFGHIJKLMNOPQRSTUVW' 

RETURN 
END ♦ 

.4 Recovering from Stack Corruption 

The debugger allocates a certain amount of memory at startup and shares the 
stack with the user’s program. If a user process exception results in exhaustion of 
resources or corruption of the stack, the debugger may be incapable of regaining 
control, and the debug session may terminate. 

Be aware of this potential behavior after the occurrence of stack corruption 
messages or warnings about continuing from a severe error. In either case, the 
integrity of the debug session cannot be guaranteed. 

It is recommended that you try one of the following measures! 

• Change your source code, temporarily or permanently, to reduce resource 
consumption or lessen the use of stack space 

• Increase quotas 

• Specify a larger stack size when linking your program 

5 Debugging Exceptions and Condition Handlers 

A condition handler is a procedure that the operating system executes when an 
exception occurs. 

Exceptions include hardware conditions (such as an arithmetic overflow or 
a memory access violation) or signaled software exceptions (for example, an 
exception signaled because a file could not be found). 

Operating system conventions specify how, and in what order, various condition 
handlers established by the operating system, the debugger, or your own program 
are invoked—for example, the primary handler, call frame (application-declared) 
handlers, and so on. Section 13.5.3 describes condition handling when you are 
using the debugger. See the OpenVMS Run-Time Library Routines Volume for 
additional general information about condition handling. 

Tools for debugging exceptions and condition handlers include the following: 

• The SET BREAK/EXCEPTION and SET TRACE/EXCEPTION commands, 
which direct the debugger to treat any exception generated by your 
program as a breakpoint or tracepoint, respectively (see Section 13.5.1 
and Section 13.5.2). 

• Several built-in symbols (such as %EXC_NAME), which enable you to qualify 
exception breakpoints and tracepoints (see Section 13.5.4). 
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• The SET BREAK/EVENT and SET TRACE/EVENT commands, which enable 
you to break on or trace exception events that are specific to Ada, SCAN, 
or multithread programs (see the corresponding documentation for more 
information). 


13.5.1 Setting Breakpoints or Tracepoints on Exceptions 

When you enter a SET BREAK/EXCEPTION or SET TRACE/EXCEPTION 
command, you direct the debugger to treat any exception generated by your 
program as a breakpoint or tracepoint. As a result of a SET BREAK/EXCEPTION 
command, if your program generates an exception, the debugger suspends 
execution, reports the exception and the line where execution is paused, and 
prompts for commands. The following example shows the effect: 


DBG> SET BREAK/EXCEPTION 
DBG> GO 


%SYSTEM-F-INTDIV, arithmetic trap, integer divide by zero at PC-0000066C, PSL 03C00022 
break on exception preceding TEST\%LINE 13 
6: X := 3/Y; 

DBG> 

Note that an exception breakpoint (or tracepoint) is triggered even if your 
program has a condition handler to handle the exception. The SET BREAK 
/EXCEPTION command causes a breakpoint to occur before any handler can 
execute (and possibly dismiss the exception). Without the exception breakpoint, 
the handler will be executed, and the debugger would get control only if no 
handler dismissed the exception (see Section 13.5.2 and Section 13.5.3). 

The following command line is useful for identifying where an exception occurred. 
It causes the debugger to automatically display the sequence of active calls and 
the PC value at an exception breakpoint: 

DBG> SET BREAK/EXCEPTION DO (SET MODULE/CALLS; SHOW CALLS) 

You can also create a screen-mode DO display that issues a SHOW CALLS 
command whenever the debugger interrupts execution. For example. 

DBG> DISPLAY CALLS DO (SET MODULE/CALLS; SHOW CALLS) 

An exception tracepoint (established with the SET TRACE/EXCEPTION 
command) is like an exception breakpoint followed by a GO command without an 
address expression specified. 

An exception breakpoint cancels an exception tracepoint, and vice versa. 

To cancel exception breakpoints or tracepoints, use the CANCEL BREAK 
/EXCEPTION or CANCEL TRACE/EXCEPTION command, respectively. 

13.5.2 Resuming Execution at an Exception Breakpoint 

When an exception breakpoint is triggered, execution is paused before any 
application-declared condition handler is invoked. When you resume execution 
from the breakpoint with the GO, STEP, or CALL commands, the behavior is as 
follows: 

• Entering a GO command without an address-expression parameter, or 
entering a STEP command, causes the debugger to resignal the exception. 
The GO command enables you to observe which application-declared handler, 
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• f f n ^ ne ? h ^ ndles tlle exception. The STEP command causes you to step 
into that handler (see the next example). 

Entering a GO command with an address-expression parameter causes 
execution to resume at the specified location, which inhibits the execution of 
any application-declared handlers. 

A common debugging technique at an exception breakpoint is to call a dump 
routine with the CALL command (see Chapter 12). When you enter the 
CALL command at an exception breakpoint, no breakpoints, tracepoints, or 
watchpomts that were previously set within the called routine are active, so 
that the debugger does not lose the exception context. After the routine has 
executed, the debugger prompts for input. Entering a GO or STEP command 
at this point causes the debugger to resignal the exception. 

The following FORTRAN example shows how to determine the presence of a 
condemn handler at an exception breakpoint and how a STEP command, entered 
at the breakpoint, enables you to step into the handler. 

At the exception breakpoint, the SHOW CALLS command indicates that the 
exception was generated during a call to routine SYS$QIOW: 

DBG> SET BREAK/EXCEPTION 
DBG> GO 


%SYSTEM-F-SSFAIL, system service failure 
break on exception preceding SYS$QI0W+6 
DBG> SHOW CALLS 

module name routine name line 

SYS$QI0W 

*EXC$MAIN EXC$MAIN 23 

DBG> 


exception, status=0000013C, PC=7FFEDE06, 


rel PC abs PC 

00000006 7FFEDE06 
0000003B 0000063B 


PSL=03C00000 


P n Processors, the following SHOW STACK command indicates that no 
handler is declared in routine SYS$QIOW. However, one level down the call 
stack, routine EXC$MAIN has declared a handler named SSHAND: 

DBG> SHOW STACK 
stack frame 0 (2146296644) 
condition handler: 0 
SPA: 0 

S: 0 

mask: A M<R2,R3,R4,R5,R6,R7,R8,R9,R10,R11> 

PSW: 0020 (hexadecimal) 

saved AP: 2146296780 

saved FP: 2146296704 

saved PC: EXC$MAIN\%LINE 25 
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stack frame 1 

(2146296704) 

condition 

handler: SSHAND 

SPA: 

0 

S: 

0 

mask: 

A M<R11> 

PSW: 

0000 (hexadecimal) 

saved AP: 

2146296780 

saved FP: 

2146296760 

saved PC: 

SHARE$DEBUG+2217 


. ♦ 

At this exception breakpoint, entering a STEP command enables you to step 
directly into condition handler SSHAND: 


DBG> STEP 

stepped to routine SSHAND 

2 : INTEGER*4 FUNCTION SSHAND (SIGARGS, MECHARGS) 

DBG> SHOW CALLS 

module name routine name line rel PC PC 

*SSHAND SSHAND 2 00000002 00000642 

- above condition handler called with exception 00000 45 C: PS L=03C00000 

ISYSTEM-F-SSFAIL, system service failure exception, status-0000013C, PC 7FF , 

- end of exception message 

SYS$QIOW 00000006 7FFEDE06 

*EXC$MAIN EXC$MAIN 23 0000003B 0000063B 

DBG> 


The debugger symbolizes the addresses of condition handlers into names if that 
is possible. However, note that with some languages, exceptions are first handled 
by a run-time library (RTL) routine, before any application-declared condition 
handler is invoked. In such cases, the address of the first condition handler might 
be symbolized to an offset from an RTL shareable image address. 


13.5.3 Effect of the Debugger on Condition Handling 

When you run your program with the debugger, at least one of the following 
condition handlers is invoked, in the order given, to handle any exceptions caused 
by the execution of your program: 

1. Primary handler 

2. Secondary handler 

3. Call-frame handlers (application-declared)—also known as stack handlers 

4. Final handler 

5. Last-chance handler 

6. Catchall handler 

A handler can return one of the following three status codes to the Condition 
Handling Facility: 

• SS$_RESIGNAL—The operating system searches for the next handler. 

• SS$ CONTINUE—The condition is assumed to be corrected and execution 
continues. 

• SS$_UNWIND—The call stack is unwound some number of frames, if 
necessary, and the signal is dismissed. 

For more information about condition handling, see the OpenVMS Programming 
Concepts Manual. 
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13.5.3.1 Primary Handler 

When you run your program with the debugger, the primary handler is the 
debugger. Therefore, the debugger has the first opportunity to handle an 
exception, whether or not the exception is caused by the debugger. 

If you enter a SET BREAK/EXCEPTION or SET TRACE/EXCEPTION command 
the debugger breaks on (or traces) any exceptions caused by your program The ? 
break (or trace) action occurs before any application-declared handler is invoked. 

If you do not enter a SET BREAK/EXCEPTION or SET TRACE/EXCEPTION 
command, the primary handler resignals any exceptions caused by your program. 

13.5.3.2 Secondary Handler 

The secondary handler is used for special purposes and does not apply to the 
types of programs covered in this manual. 

13.5.3.3 Call-Frame Handlers (Application-Declared) 

Each routine of your program can establish a condition handler, also known as 
a call-frame handler. The operating system searches for these handlers starting 
with the routine that is currently executing. If no handler was established for 
that routine, the system searches for a handler established by the next routine 
down the call stack, and so on back to the main program, if necessary. 

After it is invoked, a handler might perform one of the following actions: 

It handles the exception, which allows the program to continue execution. 

It resignals the exception. The operating system then searches for another 
handler down the call stack. 

It encounters a breakpoint or watchpoint, which suspends execution at the 
breakpoint or watchpoint. 

It generates its own exception. In this case, the primary handler is invoked 
again. 

• It exits, which terminates program execution. 

13.5.3.4 Final and Last-Chance Handlers 

These handlers are controlled by the debugger. They enable the debugger to 
regain control and display the DBG> prompt if no application-declared handler 
has handled an exception. Otherwise, the debugging session will terminate and 
control will pass to the DCL command interpreter. 

The final handler is the last frame on the call stack and the first of these two 
handlers to be invoked. The following example shows what happens when an 
unhandled exception is propagated from an exception breakpoint to the final 
handler: 

DBG> SET BREAK/EXCEPTION 
DBG> GO 


-oSYSTEM F-INTDIV, arithmetic trap, integer 
break on exception preceding TEST\%LINE 13 
6: X := 3/Y; 

DBG> GO 

%SYSTEM-F-INTDIV, arithmetic trap, integer 
DBG> 


divide by zero at PC=0000066C, 
divide by zero at PC=0000066C, 


PSL=03C00022 


PSL=03C00022 
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In this example, the first INTDIV message is issued by the primary handler, and 
the second is issued by the final handler, which then displays the DBG> prompt. 

The last-chance handler is invoked only if the final handler cannot gain control 
because the call stack is corrupted. For example: 

DBG> DEPOSIT %FP = 10 
DBG> GO 


%SYSTEM-F-ACCVIO, access violation, reason mask=00, virtual address=0000000A, PC-0000319C, PSL-03C00000 

%DEBUG-E-LASTCHANCE / stack exception handlers lost, re-initializing stack 

DBG> 

The catchall handler, which is part of the operating system, is invoked if the 
last-chance handler cannot gain control. The catchall handler produces a register 
dump. This should never occur if the debugger has control of your program, 
but it can occur if your program encounters an error when running without the 
debugger. 

If, during a debugging session, you observe a register dump and are returned to 
DCL level ($), submit a Software Performance Report (SPR) to Digital. 

13.5.4 Exception-Related Built-In Symbols 

When an exception is signaled, the debugger sets the following exception-related 


built-in symbols: 

Symbol 

Description 

%EXC_FACILITY 
%EXC_NAME 
%ADAEXC_NAME 
%EXC_NUMBER 
%EXC SEVERITY 

Name of facility that issued the current exception 

Name of current exception 

Ada exception name of current exception (for Ada programs only) 
Number of current exception 

Severity code of current exception 


You can use these symbols as follows: 


• To obtain information about the fields of the condition code of the current 
exception. 

• To qualify exception breakpoints or tracepoints so that they trigger only on 
certain kinds of exceptions. 

The following examples show the use of some of these symbols. Note that the 
conditional expressions in the WHEN clauses are language-specific. 


DBG> EVALUATE %EXC_NAME 
'ACCVIO' 

DBG> set trace/exception when (%EXC_NAME = "ACCVIO") 


DBG> EVALUATE %EXC_FACILITY 
'SYSTEM' 

DBG> EVALUATE %EXC_NUMBER 
12 

DBG> EVALUATE/CONDITION_VALUE %EXC_NUMBER 
%SYSTEM-F-ACCVIO, access violation, reason mask=01 
DBG> SET BREAK/EXCEPTION WHEN (%EXC_NUMBER = 12) 
DBG> SET BREAK/EXCEPTION WHEN (%EXC_SEVERITY .NE. 


, virtual address=FFFFFF30, 
"I" .AND. %EXC SEVERITY .NE. 


PC=00007552, 

"S") 


PSL=03C00000 
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13.6 


Debugging Exit Handlers 

4 pvrt andl i erS are P rocedures that are called whenever an image requests the 
XIT system service or runs to completion. A user program can declare one or 
more exit handlers. The debugger always declares its own exit handler. 

At program termination, the debugger exit handler executes after all application- 
declared exit handlers have executed. 

To debug an application-declared exit handler: 

1. Set a breakpoint in that exit handler. 

2. Cause the exit handler to execute by using one of the following techniques: 

• Include in your program an instruction that invokes the exit handler 
(usually a call to $EXIT). 

• Allow your program to terminate. 


• Enter the EXIT command. (Note that the QUIT command does not 
execute any user-declared exit handlers.) 

When the exit handler executes, the breakpoint is activated and control is 
then returned to the debugger, which prompts for commands. 


The SHOW EXIT_HANDLERS command gives a display of the exit handlers 
that your program has declared. The exit handler routines are displayed in 
the order that they are called. A routine name is displayed symbolically if 
possible Otherwise, its address is displayed. The debugger’s exit handle’rs are 
not displayed. For example: 


DBG> SHOW EXIT_HANDLERS 
exit handler at STACKS\CLEANUP 
exit handler at BLIHANDLER\HANDLER1 
DBG> 


13.7 Debugging AST-Driven Programs 

A program can use asynchronous system traps (ASTs) either explicitly or 
implicitly by calling system services or run-time library (RTL) routines that 
call application-defined AST routines. Section 13.7.1 explains how to facilitate 

debugging by disabling and enabling the delivery of ASTs originating with your 
program. J 

13.7.1 Disabling and Enabling the Delivery of ASTs 

Debugging AST-driven programs can be confusing because interrupts originating 
trom the program being debugged can occur, but are not processed, while 
the debugger is running (processing commands, tracing execution, displaying 
information, and so on). 

mQ d * e Di U 5*™ delivery of ASTs is enabled while the program is running. The 
DISABLE AST command disables the delivery of ASTs while the program is 
running and causes any such potential interrupts to be queued. 

The delivery of ASTs is always disabled when the debugger is running. 

i f a m StatlC jTu tCh j 0mt iS in effect ’ the debugger deactivates the static watchpoint 
ABis, and thread switching, just before a system service call. The debugger 
reactivates them just after the system service call completes. (For more 
information, see the SET WATCH command description.) 
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The ENABLE AST command reenables the delivery of ASTs, including any 
pending ASTs. The SHOW AST command indicates whether the delivery of Abls 

is enabled or disabled. 

To control the delivery of ASTs during the execution of a routine called with 
the CALL command, use the /[NO]AST qualifiers. The command CALL/AST 
enables the delivery of ASTs in the called routine. The command ^ALL/NOAbi 
disables the delivery of ASTs in the called routine. If you do not specify /Abi or 
/NOAST with the CALL command, the delivery of ASTs is enabled unless you 
have previously entered the DISABLE AST command. 


13.8 Debugging Translated Images 


Alpha 


On OpenVMS Alpha systems, the debugger does not support attempts to debug 
translated images. If you must debug a translated image, use the DelWXDelta 
Debugger. For more information on this debugger, see the OpenVMS Delta 
IXDelta Debugger Manual. ♦ 


13-26 





__ 14 

Debugging Multiprocess Programs 


This chapter describes features of the debugger that are specific to multiprocess 
programs (programs that run in more than one process). These features enable 
you to display process information and control the execution of specific processes 
You can use these features in addition to those explained in other chapters. 

The first section describes the two multiprocess models for multiprocess 
programs. Remaining sections detail the basic multiprocessing techniques 
multiprocessing commands, and supplemental information. 

Images discussed in this chapter are debuggable images-that is, images that can 
e fought under control of the debugger. A debuggable image is one that was 
no inked with the /NOTRACEBACK qualifier. As explained in Section 5.2, you 
have full symbolic information when debugging an image only if its modules were 
compiled and linked with the /DEBUG qualifier. 


Alpha 


n OpenVMS Alpha systems, the debugger does not support attempts to debug 
translated images. If you must debug a translated image, use the Delta/XDelta 
Debugger. For more information on this debugger, see the OpenVMS Delta 
/XDelta Debugger Manual. ♦ 


14.1 Multiprocessing Models 

Multiprocessing programs conform to one of the following multiprocessing models: 
• The hierarchical model 


The multiprocessing program spawns processes to handle programming tasks 
and initiates connections to each process. 

• The client/server model 

The user, or client, initiates connection to the server, which processes client 
requests. The server spawns threads to handle programming tasks. 

Debugger multiprocessing features and commands support both multiprocessing 
models, but process relationships may differ depending on your invocation of the 


14.2 Basic Multiprocess Debugging Techniques 

This section gives an overview of the multiprocess debugging environment and 
explains the basic techniques used to debug a multiprocess program. Refer to 
subsequent sections for additional details. 
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14.2.1 Starting a Multiprocess Debugging Session 

This section explains the usual way of starting a multiprocess debugging 
session See Section 14.3.4 for additional techniques for starting the debugger by 
interrupting the execution of an image and bringing the image under debugger 
control (for example, using the Ctrl/Y-DEBUG sequence or the CONNECT 
command). 

To start a multiprocess debugging session, follow these steps: 

1. Establish a multiprocess debugging configuration by entering the following 
logical-name definition: 

$ DEFINE/GROUP DBG$PROCESS MULTIPROCESS 

This command establishes a multiprocess configuration for the User 
Identification Code (UIC) group in which the process originates. As a result 
any debuggable image associated with the same UIC group can be controlled 
from that one session. 

2. Start the debugger in the usual way: 

$ DEBUG/KEEP 

Debugger Banner and Version Number 
DBG> RUN prog-name 

%DEBUG-I-INITIAL, language is FORTRAN, module set to MAIN_PROG 
4DEBUG-I-N0TATMAIN, type GO to get to start of main program 
predefined trace o* activation at routine MAIN_PR0G in %PROCESS_NUMBER 1 

DBG_1> 

DBG> 

As with a one-process program, the debugger displays its banner, prompts for 
commands, and suspends execution just prior to the start of execution of the main 
image. However, note two differences: 

• The debugger prompt, which changes to (DBG_1>) after the program is 
brought under control. 


The "predefined trace on 


message 


The significance of the prompt suffix (_1) is explained Section 14.2.2. 

In a multiprocess configuration, the debugger traces each new process that is 
brought under control. In this case, the debugger traces the first process, which 
runs the main image of the program. (%PROCESS_NUMBER is a built-in symbol 
that identifies a process number, just as %LINE identifies a line number.) 


See Section 14.3.1 for more information about debugging configurations and 
process relationships. See Section 14.3.9 for system requirements related to 
multiprocess debugging. 


14.2.2 Visible Process and Process-Specific Commands 

The previous example shows that the debugger prompt in a multiprocess 
debugging configuration is different from that found in the default configuration 
(after the program is brought under debugger control). 

In a multiprocess configuration, dynamic prompt setting is enabled by default 
(SET PROMPT/SUFFIX=PROCESS_NUMBER). Therefore, the prompt has a 
process-specific suffix that indicates the process number of the visible process. 
The debugger assigns a process number sequentially, starting with process 1, to 
each process that comes under the control of a given debugging session. 
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Prn J b e P fl° CeSS 1S th ® default context for issuing process-specific commands. 
Process-specific commands start execution (STEP, GO, and so on) and look 

up symbols, set breakpoints, look at the call stack and registers, and so on 
Commands that are not process specific do not depend on the mapping of memory 
t, rather, affect the entire debugging environment (for example, keypad mode 
and screen mode commands). 

Unless dynamic prompt setting is disabled (SET PROMPT/NOSUFFIX) the 

l>) U The r SFTPRnM^T 31 ^ 8 idantifies J the visible P roc ess (for example, DBG_ 
1». the SET PROMPT command provides several options for tailoring the 
prompt-stnng prefix and suffix to your needs. 

Obtaining Information About Processes 

Use the SHOW PROCESS command to obtain information about processes 

PT?n?FecT n i t y under control of your debugging session. By default, SHOW 
FKOCESS displays one line of information about the visible process. The 

startthe deb^glr Sh ° WS ^ ° f information dis P la yed immediately after you 


DBG_1> SHOW PROCESS 
Number Name 
* 1 JONES 

DBG 1> 


Hold State 

activated 


Current PC 
MAIN PROGULINE 2 


A one-line SHOW PROCESS display provides the following information about 
each process specified: 

The process number assigned by the debugger. In this case, the process 
number is 1 because this is the first process known to the debugger. The 
asterisk in the leftmost column (*) marks the visible process. 

The process name. In this case, the process name is JONES. 

Whether the process has been put on hold with a SET PROCESS/HOLD 
command, as explained in Section 14.2.6.2. (This process has not been put on 

• The current debugging state for that process. A process is in the activated 
state when it is first brought under debugger control (that is, before it has 
executed any part of the program under debugger control). Table 14-1 

summarizes the possible debugging states that can appear in the state 
column. 

The location (symbolized, if possible) where execution of the image is paused 
in that process. In this case, the image has not started execution. 


Table 14-1 

Debugging States 

State 

Description 

Activated 

The image and its process have just been brought under 

debugger control. 

Break 1 

A breakpoint was triggered. 

See the SHOW FKOCESS command description for a list of additional states. 


(continued on next page) 
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Table 14-1 (Cont.) 

Debugging States 

State 

Description 

Interrupted 

Execution was interrupted in that process, either because 

execution was suspended in another process, or because 
the user interrupted execution with the abort-key sequence 
(Ctrl/C, by default). 

Step 1 

A STEP command has completed. 

Terminated 

The image has terminated execution but the process is 
still under debugger control. Therefore, you can obtain 
information about the image and its process. 

Trace 1 

A tracepoint was triggered. 

Unhandled exception 

Watch of 

An unhandled exception was encountered. 

A watchpoint was triggered. 


1 See the SHOW PROCESS command description for a list of additional states. 


The SHOW PROCESS/ALL command provides information about all processes 
that are currently under debugger control (in the case of the previous example, 
a SHOW PROCESS/ALL command would show only process 1). Ihe biritjw 
PROCESS/FULL command provides additional details about processes. 


Returning to the previous example, if you now enter a STEP “mm“d followed 
by a SHOW PROCESS command, the state column in the SHOW PKOCh-bb 
display indicates that execution is paused at the completion of a step: 


DBG_1> SHOW PROCESS 
Number Name Hold State 

* 1 JONES step 

DBG 1> 


Current PC 
MAIN PROGULINE 3 


Similarly, if you were to set a breakpoint and enter a GO command, a SHOW 
PROCESS command entered at the prompt after the breakpoint has triggered 
would identify the state as break. 


14.2.4 Bringing a Spawned Process Under Debugger Control 

Continuing with the example from the last section, assume that you have entered 
a few more STEP commands and, in the middle of a step, MAIN.PROG spawns a 
process to run a debuggable image called TEST. 

Because DBG$PROCESS has the value MULTIPROCESS, the spawned process is 
now requesting to connect to the current debugging session, and the image lEb 
is paused at the start of execution. 

While the spawned process is waiting to be connected, it is not yet known to the 
debugger and cannot be identified in a SHOW PROCESS/ALL display. You can 
bring the process under debugger control using either of the following methods: 

. Enter a command, such as STEP, that starts execution (if, as in this example, 
your program is of the hierarchical model). 
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Enter the CONNECT command without specifying a parameter (if your 
program is of the hierarchical or client/server model). The CONNECT 

further”* 1 * Preferable in Cases when you do not want the program to execute 

The following example shows use of the CONNECT command: 

DBG_1> STEP 

stepped to MAIN_PROG\%LINE 18 in %PROCESS NUMBER 1 
18: LIB$SPAWN("RUN/DEBUG TEST") 

DBG_1> STEP 

stepped to MAIN_PROG\%LINE 21 in %PR0CESS NUMBER 1 
21: X = 7 

DBG_1> CONNECT 

trace on activation at routine TEST in %PR0CESS NUMBER 2 
DBG — 


In this example, the second STEP command takes you past the LIB$SPAWN call 
that spawns the process. The CONNECT command brings the waiting process 
under debugger control. After entering the CONNECT command, you might 
need to wait a moment for the process to connect. The "predefined trace on ... - 
message as explained in Section 14.2.1, indicates that the debugger has taken 
control of a new process and identifies that process as process 2, the second 
process known to the debugger in this session. 

A SHOW PROCESS/ALL command, entered at this point, identifies the debugging 
state for each process and the location at which execution is paused: 

DBG_1> SHOW PROCESS/ALL 

Number Name Hold State Current PC 

1 J0NES Step MAIN_PROG\%LINE 21 

2 J0NES_1 activated TEST\%LINE 1+2 

DBG_1> 

Note that the CONNECT command brings any processes that are waiting to be 
connected to the debugger under debugger control. If no processes are waiting 
you can press Ctrl/C to abort the CONNECT command and display the debugger 


Depending on the version of the debugger you are running on your system, you 
may be restricted to connection with processes you created. For more information 
see the CONNECT command in online help. 


Unexpected results can occur if you enter the CONNECT command 
before you have confirmed that debugger logicals (DEBUG, DEBUGSHR 
DEBUGUISHR, DBGTBKMSG, DBG$PROCESS, DBG$HELP, DBG$UIHELP 

DEBUGAP pCLASS , and VMSDEBUGUIL) translate to the same definitions for 
both debugger and target process. 


14.2.5 Broadcasting Commands to Specified Processes 

By default, process-specific commands are executed in the context of the visible 
process. The DO command enables you to execute commands in the context of 
one or more processes that are currently under debugger control. This is also 
referred to as broadcasting commands to processes. 

Use the DO command without a qualifier to execute commands in the context of 

nATT T processes ' For example, the following command executes the SHOW 

° j o S coaimand for a11 Processes currently under debugger control (processes 1 
and 2, in this case): 
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DBG_1> DO (SHOW CALLS) 

For %PROCESS_NUMBER 1 

module name routine name 

*MAIN_PR0G MAIN_PROG 

For %PROCESS_NUMBER 2 

module name routine name 

TEST TEST 


line 

21 

rel PC 
0000001E 

abs PC 
0000041E 

line 

1+2 

rel PC 
0000000B 

abs PC 
0000040B 


As indicated in this example, the debugger identifies the process associated with 
any debugger output. 

Use the DO command with the /PROCESS= qualifier to execute commands in the 
context of specific processes. For example, the following command executes the 
SET MODULE START and EXAMINE X commands in the context of process 2: 


DBG 1> D0/PR0CESS=(%PR0C 2) (SET MODULE START; EXAMINE X) 


For more information about how to specify processes in debugger commands, see 
Section 14.3.2. 


14.2.6 Controlling Execution 

Program execution in a multiprocess debugging environment follows these 
conventions: 

• When you enter a command that starts program execution, such as STEP or 
GO, the command is executed in the context of the visible process. However, 
images in any other processes that have not been put on hold (with a SET 
PROCESS/HOLD command) are also allowed to execute. Similarly, if you use 
the DO command to broadcast a command to start execution in one or more 
processes, the command is executed in the context of each specified process 
that is not on hold, but images in any other processes that are not on hold are 
also allowed to execute. In all cases, a hold condition is ignored in the visible 
process. (See Section 14.2.6.2 for additional information about the behavior of 
processes on hold.) 

• After execution is started, the way in which it continues depends on whether 
the SET MODE [NOJINTERRUPT command was entered. By default (SE1 
MODE INTERRUPT), execution continues until it is paused in any process. 
At that point, execution is interrupted in any other processes that were 
executing images, and the debugger prompts for input. 

These concepts are shown next by continuing with the example in Section 14.2.4 
that shows the use of the CONNECT command. 


In that example, the "stepped to ... " messages indicate that both commands 
are executed in the context of process 1, the visible process. The second 
STEP command spawns process 2. The SHOW PROCESS/ALL example of 
Section 14.2.4 indicates that execution in processes 1 and 2 is paused at MA1JN_ 
PROG\ %LINE 21 and TEST\ %LINE 1+2, respectively. 


At this point, entering another STEP command followed by SHOW PROCESS 
/ALL results in the following display: 


DBG 1> STEP 

stepped to MAIN PR0G\%LINE 23 in -6PR0CESS_NUMBER 


1 


23: Y = 15 

DBG_1> SHOW PROCESS/ALL 
Number Name Hold State 
* 1 JONES step 

2 J0NES_1 interrupted 

DBG 1> 


Current PC 
MAIN_PROG\%LINE 23 
TEST\%LINE 3+1 
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The STEP command is executed in the context of process 1, the visible 
process. After the STEP command, execution in process 1 is paused at MAIN_ 
PROG\ %LINE 23. However, the STEP command also causes execution to start 
m process 2. The completion of the STEP command in process 1 causes execution 
in process 2 to be interrupted at TEST\ %LINE 3+1. 

Section 14.2.6.1 describes another mode of execution, which is provided bv the 
SET MODE NOINTERRUPT command. y 

14.2.6.1 Controlling Execution with SET MODE NOINTERRUPT 

The SET MODE NOINTERRUPT command allows execution to continue without 
interruption in other processes when it is suspended in some process. This is 
especially useful if, for example, you want to broadcast a STEP command to 
several processes with the DO command, then complete execution of the STEP 
command in all these processes. For example: 

DBG_1> SET MODE NOINTERRUPT 
DBG_1> DO (STEP) 

In this example, the DO command executes the STEP command in the context of 
all processes. The visible process and any other processes that are not on hold 
start execution. Because the SET MODE NOINTERRUPT command was entered, 
the prompt is displayed only after the STEP command has completed execution 
(or execution has been otherwise suspended at a breakpoint or watchpoint) in all 
processes that were executing. 

When SET MODE NOINTERRUPT is in effect, as long as execution continues in 
any process, the debugger does not prompt for input. In such cases, use Ctrl/C to 
interrupt all processes and display the prompt. 

14.2.6.2 Putting Specified Processes on Hold 

As indicated in the previous sections, a command that starts execution is executed 
in the context of the visible process, but it also causes execution to start in other 
processes. If you want to inhibit execution in a process, put it on hold For 
example, the following SET PROCESS/HOLD command puts process 2 on hold. 
The subsequent STEP command is executed in the context of process 1, the visible 
process. Execution also starts in any other processes that are not on hold, but not 
in process 2: 

DBG_1> SET PROCESS/HOLD %PROC 2 
DBG_1> STEP 

A SHOW PROCESS display indicates whether a process is on hold. For example: 

DBG_1> SHOW PROCESS/ALL 

Number Name Hold State Current PC 

1 JONES step MAIN_PROG\%LINE 24 

2 J0NES_1 HOLD interrupted TEST\%LINE 3+1 

DBG_1> 

To release a process from the hold condition, enter the SET PROCESS/NOHOLD 
command, and specify the process. 

Note that a hold condition is ignored in the visible process. Therefore, the SET 
PROCESS/HOLD/ALL command is a convenient way to confine execution to the 
visible process. In the following example, execution starts only in the visible 
process: 

DBG_1> SET PROCESS/HOLD/ALL 
DBG 1> STEP 
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This feature is useful if, for example, you want to use the CALL command to 
execute a dump routine that is not part of the execution stream of your program. 

The previous discussions also apply if you use the DO command to broadcast 
a GO, STEP, or CALL command to several processes. The GO, STEP or CALL 
command is executed in the context of each specified process that is not on hold, 
and execution also starts in any other process that is not on hold. The following 
example shows the execution behavior when all processes are put on hold and 
commands are broadcast to all processes. Execution starts only in the visible 
process (process 1, in this example): 

DBG_1> SET PROCESS/HOLD/ALL 
DBG_1> DO (EXAMINE X; STEP) 

For %PROCESS_NUMBER 1 
MAIN_PROG\X: 78 

For %PROCESS_NUMBER 2 
TEST\X: 29 

g^gppgcl to MAIN PR0G\%LINE 26 in ■sPROCESS^NUMBER 1 

26: K = K + _ 1 

DBG_1> 

14.2.7 Changing the Visible Process 

Use the SET PROCESS command (with the default /VISIBLE qualifier) to 
establish another process as the visible process. For example, the following 
command makes process 2 the visible process: 

DBG_1> SET PROCESS %PROC 2 
DBG_2> 

In this example, because dynamic prompt setting is enabled by default, the SET 
PROCESS command also has caused the prompt string suffix to change. It now 
indicates that process 2 is the visible process. All process-specific commands 
are now executed in the context of process 2. For example, a SHOW CALLS 
command would display the call stack for the image running in process 2. 

14.2.8 Dynamic Process Setting 

By default, dynamic process setting is enabled (SET PROCESS/DYNAMIC). 

As a result, whenever the debugger suspends program execution and displays 
its prompt, the process in which execution is suspended becomes the visible 
process automatically. Dynamic process setting occurs in the following situations: 
when a breakpoint or watchpoint is triggered, at an exception condition, on the 
completion of a STEP command, or when the last process performs an image exit. 

When dynamic process setting is disabled (/NODYNAMIC), the visible process 
remains unchanged until you specify another process with the SET PROCESS 
/VISIBLE command. 

Dynamic process setting is shown in the following example, which also shows 
dynamic prompt setting: 
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DBG_1> SHOW PROCESS/ALL 

Number Name Hold State Current PC 

1 J0NES step MAIN_PROG\%LINE 22 

2 J0NES_1 interrupted TEST\%LINE 4 

DBG_1> D0/PR0CESS=(%PR0C 2) (SET BREAK %LINE 11) 

DBG 1> GO 


break at TEST\%LINE 11 in %PR0CESS NUMBER 2 
DBG_2> SHOW PROCESS/ALL 

Number Name Hold State Current PC 

1 JONES interrupted MAIN_PROG\%LINE 28 

2 J0NES_1 break TEST\%LINE 11 

DBG_2> 

In this example, process 1 is initially the visible process, as indicated by the 
prompt and the SHOW PROCESS display. The DO command sets a breakpoint 
in the context of process 2. Execution is resumed with the GO command and is 
suspended at the breakpoint in process 2. Process 2 is now the visible process as 
indicated by the prompt and the SHOW PROCESS display. 

If you have entered the SET MODE NOINTERRUPT command and then started 
execution in several processes with the DO command, the prompt is displayed 
only after execution has been suspended in all processes. In this case, the visible 
process remains unchanged, unless the last process performs an image exit (and 
thereby becomes the visible process). 

14.2.9 Monitoring the Termination of Images 

When the main image of a process runs to completion, the process goes into the 
terminated debugging state (not to be confused with process termination in the 
operating system sense). This condition is traced by default, as if you had entered 
the SET TRACE/TERMINATING command. 

When a process is in the terminated debugging state, it is still known to the 
debugger and appears in a SHOW PROCESS/ALL display. You can enter 
commands to examine variables, and so on. 

When the last image of the program exits, the debugger gains control and 
displays its prompt. 

14.2.10 Releasing a Process From Debugger Control 

Tb release a process from debugger control without terminating the process, enter 
the DISCONNECT command. (In contrast, when you specify a process with the 
EXIT or QUIT command, the process is terminated.) 

This command is required for programs of the client/server model. For example 
the following command disconnects the JONES image: 

DBG> DISCONNECT JONES 
DBG> 

See Section 14.3.5 for information on DISCONNECT command restrictions and 
cautions. 
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14.2.11 Terminating Specified Processes 

To terminate specified processes without ending the debugging session, use 
the EXIT or QUIT command, specifying one or more process specifications as 
parameters. For example, the following command terminates the image running 
in process 2 and terminates the process: 

DBG_3> EXIT %PR0C 2 
DBG_3> 

Subsequently, process 2 does not appear in a SHOW PROCESS display. See the 
the EXIT and QUIT command descriptions. 

14.2.12 Interrupting Program Execution 

Pressing Ctrl/C (or the abort-key sequence established with the SET ABORT. 
KEY command) interrupts execution in every process that is currently running an 
image. This is indicated as an interrupted state in a SHOW PROCESS display. 

As in the default configuration, you can also use Ctrl/C to abort a debugger 
command. 

14.2.13 Ending the Debugging Session 

To end the entire debugging session, use the EXIT or QUIT command without 
specifying any parameters. 

EXIT executes any exit handlers that are declared in the program. QUIT does 
not. 

Thus, when you do not specify any parameters, the behavior of EXIT and QUIT 
is analogous to their behavior for the default debugging configuration. 

14.3 Supplemental Information 

This section provides additional details or more advanced concepts and usages 
than those covered in Section 14.2. 

14.3.1 Debugging Configurations and Process Relationships 

You can start the debugger in either the default configuration or the 
multiprocess configuration to debug programs that run in either one or 
several processes, respectively. 

The debugging configuration depends on the current definition of the logical name 
DBG$PROCESS, as indicated in the following table: 


Definition of Logical Name 
DBG$PROCESS 

Resulting Debugging Configuration 

Undefined or DEFAULT 

Default (use this configuration with a program that 

runs in one process) 

MULTIPROCESS 

Multiprocess (use this configuration with a program 
that runs in several processes) 


Note that the debugging configuration does not depend on whether the 
program runs in one or several processes. Rather, the current definition of 
DBG$PROCESS determines whether debuggable images running in different 
processes can be controlled from the same debugging session. 
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14.3.1.1 


14.3.1.2 


14.3.1.3 


debugger ’ enter the DCL com mand SHOW LOGICAL 
UBLr^KOLLbb to determine the current definition of DBG$PROCESS and 
the resulting debugging configuration. 


Establishing a Default Debugging Configuration 

Use the default configuration to debug a program that normally runs (without 
only one process. This configuration is achieved when 
is either undefined or has the definition DEFAULT. 


In the following example, the output of the SHOW LOGICAL command 
that a default debugging configuration is in effect: 


indicates 


$ SHOW LOGICAL DBG$PROCESS 

-oSHOW-S-NOTRAN, no translation for logical name DBG$PROCESS 


If DBG$PROCESS has the value MULTIPROCESS, and you want to debug a 
program that runs in only one process, enter the following command: 

$ DEFINE DBG$PROCESS DEFAULT 

Establishing a Multiprocess Debugging Configuration 

Use the multiprocess configuration to debug a program that normally runs in 
more than one process. This configuration is achieved when DBG$PROCESS 
has the definition MULTIPROCESS, and it enables you to interact with several 
processes. Use the following command to establish a multiprocess debugging 
configuration: 66 8 

$ DEFINE/GROUP DBG$PROCESS MULTIPROCESS 


Process Relationships When Debugging 

The debugger consists of two parts: A main debugger image (DEBUGSHR.EXE) 

ml C i°Tn ta i!vt m0 f ° f the debugger code and a smaller kernel debugger image 
UJJLBUG.EXE). This separation reduces potential interference between the 

debugger and the program being debugged and also makes it possible to have a 
multiprocess debugging configuration. 


When you start the debugger, a process is created to run the main debugger. 
Regardless of the configuration (default or multiprocess), the presence of a main 
debugger running in some process establishes a unique debugging session. 

When you bring a program under debugger control, the main debugger spawns a 
subprocess to run the program along with the kernel debugger. 

In the multiprocess configuration, the program being debugged runs in several 
processes. Each process that is running one or more images under debugger 
control is also running a local copy of the kernel debugger. The main debugger 

running in its own process, communicates with the other processes through their 
kernel debuggers. 


Although all processes of a multiprocess configuration must be in the same UIC 
group, they do not have to be related in a particular process/subprocess hierarchy 
Moreover, the program images running in separate processes do not have to 
communicate with each other. 


See Section 14.3.9 for system requirements related to multiprocess debugging. 
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14.3.2 Specifying Processes in Debugger Commands 

When specifying processes in debugger commands, you can use any of the forms 
listed in Table 14-2, except when specifying processes with the CONNEOl 
command (see Section 14.3.4.2). 

The CONNECT command is used to bring a process that is not yet known to 
the debugger under debugger control. Therefore, when specifying a process with 
CONNECT, you can use only its process name or process identification number 
(PID). You cannot use its debugger-assigned process number or any of the process 
built-in symbols (for example, %NEXT_PROCESS) for the process. 


Table 14-2 Process Specifications 


Format 

Usage 

[%PROCESS_NAME] process-name 

The process name, if that name contains no 

spaces or lowercase characters . 

[%PROCESS_NAME] "process-name" 

The process name, if that name contains 
spaces or lowercase characters. You can 
also use apostrophes (') instead of quotation 
marks ("). 

%PROCESS_PID processjd 

The process identification number (PID, a 
hexadecimal number). 

%PROCESS_NUMBER process-number 
(or %PROC process-number ) 

The number assigned to a process when 
it comes under debugger control. A new 
number is assigned sequentially, starting 
with 1, to each process. If a process 
is terminated with the EXIT or QUIT 
command, the number is not reused during 
the debugging session. Process numbers 
appear in a SHOW PROCESS display. 
Processes are ordered in a circular list 
so they can be indexed with the built- 
in symbols %PREVIOUS_PROCESS and 
%NEXT_PROCESS. 

process-group-name 

A symbol defined with the DEFINE 
/PROCESS_GROUP command to represent a 
group of processes. 

%NEXT_PROCESS 

The next process after the visible process in 
the debugger’s circular process list. 

%PRE VIOU S_PROCE SS 

The process previous to the visible process in 
the debugger’s circular process list. 

%VISIBLE_PROCESS 

The process whose stack, register set, and 
images are the current context for looking 
up symbols, register values, routine calls, 
breakpoints, and so on. 

i The process name can include the wildcard character ( ). 


You can omit the %PROCESS_NAME built-in symbol when entering commands. 
For example: 

DBG 2> SHOW PROCESS %PR0C 2, J0NES_3 
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You can define a symbol to represent a group of processes (DEFINE/PROCESS_ 
GROUP). This enables you to enter commands in abbreviated form. For example: 

DBG_1> DEFINE/PROCESS_GROUP SERVERS=FILE SERVER, NETWORK SERVER 
DBG_1> SHOW PROCESS SERVERS 

Number Name Hold State Current PC 

1 FILE_SERVER step FS PR0G\%LINE 37 

2 NETWORK_SERVER break NET PR0G\%LINE 24 

DBG_1> 

The built-in symbols %VISIBLE_PROCESS, %NEXT_PROCESS, and 
%PREVIOUS_PROCESS are useful in control structures based on the IF, 
WHILE, or REPEAT commands and in command procedures. 

14.3.3 Monitoring Process Activation and Termination 

By default, a tracepoint is triggered when a process comes under debugger 
control and when it performs an image exit. These predefined tracepoints are 
equivalent to those resulting from entering the SET TRACE/ACTIVATING and 
SET TRACE/TERMINATING commands, respectively. You can set breakpoints 
on these events by means of the SET BREAK/ACTIVATING and SET BREAK 
/TERMINATING commands. 

To cancel the predefined tracepoints, use the CANCEL TRACE/PREDEFINED 
command with the /ACTIVATING and /TERMINATING qualifiers. To cancel any 
user-defined activation and termination breakpoints, use the CANCEL BREAK 
command with the /ACTIVATING and /TERMINATING qualifiers (the /USER 
qualifier is assumed by default when canceling breakpoints or tracepoints). 

The debugger prompt is displayed when the first process comes under debugger 
control. This enables you to enter commands before the main image has started 
execution, as with a one-process program. 

Also, the debugger prompt is displayed when the last process performs an image 
exit. This enables you to enter commands after the program has completed 
execution, as with a one-process program. 

14.3.4 Interrupting the Execution of an Image to Connect It to the Debugger 

You can interrupt a debuggable image that is running without debugger control 
in a process and connect that process to the debugger. 

• To start a new debugging session, use the Ctrl/Y-DEBUG sequence from DCL 
level. 

• To interrupt an image and connect it to an existing debugging session use 
the CONNECT command. 

14.3.4.1 Using the Ctrl/Y-DEBUG Sequence to Start the Debugger 

You use the Ctrl/Y—DEBUG sequence with the multiprocess debugging 
configuration as with the default configuration (see Section 5.3.8.2): 

1. Run the image from DCL level with the RUN/NODEBUG command. 

2. Press Ctrl/Y to interrupt the image. 

3. Enter the DEBUG command to start the debugger. 
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The following example shows how you might start a new debugging session. 

$ DEFINE/GROUP DBG$PROCESS MULTIPROCESS 
$ RUN/NODEBUG PROG2 


[ctriTy] 

Interrupt 
$ DEBUG 

Debugger Banner and Version Number 

%DEBUG-I-INITIAL, language is FORTRAN, module set to SUB4 
predefined trace on activation at SUB4\%LINE 12 in %PROCESS_NUMBER 1 
DBG_1> 

In this example, the DEFINE/JOB command establishes a multiprocess 
debugging configuration. The RUN/NODEBUG command starts the execution of 
image PROG2 without debugger control. The Ctrl/Y-DEBUG sequence interrupts 
execution and starts the debugger. 

The debugger banner indicates that a new debugging session has been started. 
The process-specific prompt (DBG_1>) indicates that this is a multiprocess 
configuration and that execution is paused in process 1, which is running image 
PROG2. 

The activation tracepoint identifies the location at which execution was 
interrupted (and at which the debugger took control of the process). You can 
also use the SHOW CALLS command to display the call stack at that location. 

After the debugger has been started, you can use the CONNECT command to 
bring other processes under debugger control. In the previous example, you could 
use the CONNECT command to bring processes under debugger control that were 
created by PROG2 before you interrupted its execution (see Section 14.3.4.2). 

When using the Ctrl/Y-DEBUG sequence, if a multiprocess debugging session 
already exists in the same group as the image that is interrupted, the image 
connects to that session. In this case, because a new session is not started, the 
debugger banner is not displayed when the debugger takes control. This situation 
could occur if, for example, you entered a SPAWN/NOWAIT command from the 
session, started execution with a RUN/NODEBUG command, and then entered a 
Ctrl/Y-DEBUG sequence. 

14.3.4.2 Using the CONNECT Command to Interrupt an Image 

The CONNECT command, used without a parameter, was introduced in 
Section 14.2.4. When used with a parameter, the CONNECT command enables 
you to interrupt a debuggable image that is running without debugger control 
and bring it under control of your current debugging session. 

The image might have been activated as follows: 

• Your program issued a LIB$SPAWN run-time library call to spawn a process 
and run an image without debugger control 

• You started execution with a RUN/NODEBUG command entered at DCL level 

In the following example, the CONNECT command causes the image running 
in process JONES_3 to be interrupted and to come under control of the current 
debugging session. Process JONES_3 must be in the same job as the session. 

DBG 1> CONNECT J0NES_3 
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14 - 3 - 5 Pleasing a Specified Process for Continued Execution 

command to release the process without terminating “ (Tn contort ^vlu 
specify a process with the EXIT or QUIT command .‘the prccZtt^ZeZ 

;^r inVOke i he debugg f with the CTEIVY-DEBUG sequence or the RUN 
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If you are running only one process in a multiprocess configuration and 
you enter the DISCONNECT command for this process, youterSatefte 
debugger mam process. me 

^SS^ H JTT f “*t multiprocess ^figuration, and you enter 
the DISCONNECT command for the n-1 process, you terminate all processes. 

Bear in mind also, that the debugger kernel runs in the same process as the 
image being debugged. If you issue the DISCONNECT command for this process 
y u release your process, but the kernel remains activated. This activation 

Srr bu U « d the h .r 8ram image flni8hes running. If you instail a niw ^rsion 
lwr d b gg whlle one or more disconnected but activated kernels inhabit 
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14.3.6 Screen Mode Features for Multiprocess Debugging 

Screen mode displays, whether predefined or user defined, are associated with 
the visible process by default. For example, SRC shows the source code where 
executmms suspended in the visible process, OUT shows the output of commands 
executed in the context of the visible process, and so on. 

By using the /PROCESS qualifier with the DISPLAY command you can create 
The'c^nts o'f PkyS ^ dis P la ^ P™cess specific, respectively. 

DBG_2> DISPLAY/PROCESS=(%PROC 3) SRC 3 AT RS23 - 
_DBG_2> SOURCE (EXAM/SOURCE .%SOURCE~SCOPE\%PC) 

You assign attributes to process-specific displays as for displays that are not 
process specific. For example, the following command makes disDlav SRC R the 

SSS source **■» °u‘puTXroll. Z 

^aamijnl/SOURCE commands are then directed at SRC_3: 
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DBG 2> SELECT/SCROLL/SOURCE SRC_3 

Tf on * pr o niSPLAY/PROCESS command without specifying a process, the 

to the process that was the visible process when 
yru Sred the command For example, the following command makes OUT.X 
specific to process 2: 

DBG_2> display/process out_x 

TViP /SUFFIX qualifier appends a process identifying suffix that denotes the 
ESTEST. display name. This quahher can be: used^ 
display name in any command that specifies a display (for example DISPLAY, 
EXTRACT SAVE). It is especially useful within command procedures 
coupon with display definitions or key definitions that are bound to display 

definitions. 

In a multiprocess configuration, the predefined tracepoint on process activation 
automSy creates a new source display and a new instruction display for each 
new process that comes under debugger control. The displays have the name 
SRC_n and INSTn, respectively, where n is the process number P y 

are initially marked as removed. They are automatically deleted on process 

termination. 

Several predefined keypad key sequences enable you to configure your screen with 
fhl pleispSc source and instruction displays that are created automatically 
whenTprocess is activated. Key sequences that arespemhc 
programs are as follows: PF1 KP9, PF4 KP9, PF4 KP7, PF4 PF4 
See Section A.5 for the general effect of these sequences. Use the SHOW KEY 
command to determine the exact commands. 

14.3.7 Setting Watchpoints in Global Sections (VAX Only) 

on VAX processors, you can set watchpoints in global sections. A global section 
fs alegmn of menrnry that is shared among all processes of a multiprocess 
program. A watchpoint that is set on a location ini a global section (a global 
section watchpoint) triggers when any process modifies the contents of t 
location. 

When setting watchpoints on arrays or records, note that performance is 
improved if you specify individual elements rather than the entire structure 
with the SET WATCH command. 

If you set a watchpoint on a location that is not yet mapped to a Sl°bal section, 
the watchpoint is treated as a conventional static watchpoint. For exa p . 

DBG_1> SET WATCH ARR(l) 

DBG~1> SHOW WATCH 
watchpoint of PPL3\ARR(1) 

When ARR is subsequently mapped to a global section, the watchpoint is 
automatically treated as a global section watchpoint and an informational 
message is issued. For example. 
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DBG_1> GO 

%DEBUG-I-WATVARNOWGBL, watched variable PPL3\ARR(1) has 
been remapped to a global section 

predefined trace on activation at routine PPL3 in %PR0CESS NUMBER 2 
predefined trace on activation at routine PPL3 in %PROCESS~NUMBER 3 
watch of PPL3\ARR(1) at PPL3ULINE 93 in %PR0CESS NUMBER 2~ 

93: ARR(l) = INDEX 

old value: 0 
new value: 1 

break at PPL3\%LINE 94 in %PR0CESS NUMBER 2 
94: ARR(I) = I 

After the watched location is mapped to a global section, the watchpoint is visible 
from each process. For example: 

DBG_2> DO (SHOW WATCH) 

For %PROCESS_NUMBER 1 

watchpoint of PPL3\ARR(1) [global-section watchpoint] 

For %PROCESS_NUMBER 2 

watchpoint of PPL3\ARR(1) [global-section watchpoint] 

For %PROCESS_NUMBER 3 

watchpoint of PPL3\ARR(1) [global-section watchpoint] ♦ 

14.3.8 Using Multiprocess Commands with the Default Configuration 

All commands, qualifiers, and built-in symbols that are provided for multiprocess 
debugging are also understood in the default debugging configuration (provided 
you have invoked the debugger with the DEBUG/KEEP command) and have 
analogous behaviors (where applicable). For example: 

The EXIT command without a parameter ends a debugging session in both 
configurations. 

• A DO command without the /PROCESS qualifier executes the commands 
specified in all processes. 

• In the default configuration, the visible process is the process that runs the 
entire program. It is identified as process 1 in a SHOW PROCESS display. 

• Process-specific built-in symbols, such as %PROCESS_NUMBER and 
%VISIBLE_PROCESS, are interpreted correctly in the default configuration. 

This compatibility enables you to use command procedures designed for 
multiprocess debugging when debugging programs that run in only one process. 

14.3.9 System Requirements for Multiprocess Debugging 

Several users debugging multiprocess programs can place a load on a system. 

his section describes the resources used by the debugger, so that you or your 
system manager can tune your system for this activity. 

Note that the discussion covers only the resources used by the debugger. You 
might have to tune your system to support the multiprocess programs themselves. 

14.3.9.1 User Quotas 

Each user needs a PRCLM quota sufficient to create an additional process for the 
debugger, beyond the number of processes needed by the program. 

BYTLM, ENQLM, FILLM, and PGFLQUOTA are pooled quotas. They may need 
to be increased to account for the debugger process as follows: 

• Each user’s ENQLM quota should be increased by at least the number of 
processes being debugged. 
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• Each user’s PGFLQUOTA might need to be increased. If a user has an 
insufficient PGFLQUOTA, the debugger might fail to activate or cause 
"virtual memory exceeded" errors during execution. 

• Each user’s BYTLM and FILLM quotas might need to be increased. The 
debugger requires BYTLM and FILLM quotas sufficient to open each image 
file being debugged, the corresponding source files, and the debugger input, 
output, and log files. 

14.3.9.2 System Resources 

The kernel and main debugger communicate through global sections. The 
main debugger communicates with up to 8 kernel debuggers through a 65-page 
global section. Therefore, the system global-page and global-section parameters 
(GBLPAGES and GBLSECTIONS, respectively) might need to be increased. For 
example, if 10 users are using the debugger simultaneously, 10 global sections 
using a total of 650 global pages are required by the debugger. 
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Debugging Vectorized Programs (VAX Only) 


This chapter describes features of the debugger that are specific to vectorized 

additfon to^h 0 ^" 18 l that T e VeCt ° r instructions )- Use these features in 
addition to those explained in other chapters. 

The information in this chapter enables you to perform the following tasks: 

your^ystem™ 1 ^ 011 ^ aVailability and use of the vector processor on 

Control and monitor the execution of vector instructions with breakpoints 
watcnpoints, and so on ^ 9 

^ a ^ ae a “ d de Posit into the vector control registers (%VCR, %VLR, and 
%VMR) and the vector registers (%V0 to %V15) 

• Examine and deposit vector instructions and their operands 

Perform masked operations when examining vector registers or vector 
instructions to display only certain register elements or override the masking 
associated with a vector instruction 6 

When using the EXAMINE command, specify composite address expressions 
of a complex form that might be appropriate for a vectorized program 

Display the decoded results of vector floating-point exceptions 

• Control synchronization between the scalar and vector processors 

Save and restore the current vector state when using the CALL command to 
execute a routine that might affect the vector state 

• Display vector register data using a screen-mode display 

For additional information that is specific to a vectorized high-level language 
program see the associated language documentation. For complete information 
about vector instructions and vector registers, see the OpenVMS MACRO and 
instruction Set Reference Manual. 


Notes 


1. Compilers do not generate symbol-table data to associate vector 
registers with symbols declared in the program. Therefore, no 
symbolization is available for vector registers during a debugging 
session Also, you can access a vector register only in scope 0 (the 
scope of the routine at the top of the call stack). 
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2. The examples in this chapter show how to access elements of a 

vector register using array syntax (for example EXAMINE %V1(37)). 
This syntax is not supported for BLISS. In BLISS, use the SET 
LANGUAGE command to set the language temporarily to some oth 
language, such as FORTRAN, then use the array syntax for that 
language. 


15.1 Obtaining Information About the Vector Processor 

The SHOW PROCESS/FULL command provides some information about the 
availability and use of the vector processor on your system. For example: 

dbg> show process/full 


Vector capable: Ye 
Vector consumer: Ye 
Fast Vector context switches: 


DBG> 

The Vector capable field can have the following entries: 


Vector-Capable Entry 

Description 

Yes 

The VAX system has a vector processor, and it is available to the 

process that is running the program. 

No (protected) 

The VAX system has a vector processor, but the process running 
the program is denied access to the processor. 

WIEF 

The VAX system does not have a vector processor. It is running 
the VAX Vector Instruction Emulation Facility (WIEF). the 
VVIEF is available to the process that is running the program. 

No 

The VAX system does not have an active vector processor, and 
the WIEF is not loaded on the system. 


15.2 Controlling and Monitoring the Execution of Vector 
Instructions 

The following sections explain how to perform the following tasks. 

. Execute the program to (step to) either the next vector instruction or any one 
of a set of specified vector instructions. 

• Set breakpoints and tracepoints that trigger either on any vector instruction 
or on any one of a set of specified vector instructions. 

• Set watchpoints to monitor changes in vector registers. 


Vector CPU time: 0 00:03:17.18 

0 Slow Vector context switches: 
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15.2 Controlling and MoSSS^'SSK %XES££& 
15.2.1 Executing the Program to the Next Vector Instruction 

enter^heSTEJWECTOR^INSTRUCTION command enC0Untere<i in the P"*™™. 

DBG> STEP/INSTRUCTION=(VLDL,VSTL,MOVL) 

S’ s?E^lZ“ a " es you 40 change the <*««■« or 

• Enter the SET STEP VECTORJNSTRUCTION command to mate the STEP 
command execute the program to the next vector instru^on by default 

' S commal STEP ffTRUCTION-lo pcodel, ... 7, command to make the 

of oncnd.Tr i d I XeC “ h<> pr ° Bram t0 the ncxl instruction that is in the list 
of opcodes (including a vector instruction) by default. 

15.2.2 Setting Breakpoints and Tracepoints on Vector Instructions 

WECTORTNSTRUCTinS " rSSf t £ B enter the “ m ™nd CANCEL BREAK 
v Jic i UK_lNhTRUCTION or CANCEL TRACE/VECTOR_INSTRUCTION. 

You can aiso s et breakpoints and tracepoints on one or more specific vector 

ssferzfs - -*- set 

DBG> SET BREAK/INSTRUCTION (WADDL, WLEQL) 

flNSTIOTrT^^^ enter the CANCEL BREAK 

/INSTRUCTION or CANCEL TRACE/INSTRUCTION command. 

15.2.3 Setting Watchpoints on Vector Registers 

You can set watchpoints on the vector registers (VO to V15) and on the vector 

contrd registers (VCR, VLR, and VMR). Section 15.3.1 identifies these rlSsters 
and their built-in debugger symbols. S mese reglsters 

These watchpoints are treated like static watchpoints in that, once set the 
watchpoint is active until you cancel it explicitly. In the following example a 
watchpoint is set on register VCR: g exam P Ie > a 

DBG> SET WATCH %VCR 

In the case of VMR and VO to V15. you can set a watchpoint either on the 

register eWnt or oTV 8 ’ e ! ements of the agister), on an individual 

register element, or on a range of elements (a slice). Use the same technioue that 

y use to set a watchpoint on an array variable. (See Section 7.4.) 

Se ‘ S 3 Wa ‘ ChP0int that ^ any 

DBG> SET WATCH %V5 
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The following command sets a watchpoint that triggers if element 37 of V2 
changes (FORTRAN array syntax): 

DBG> SET WATCH %V2(37) 

The following command sets a watchpoint that triggers if any element of V2 in 
the range from element 5 to 13 changes. 

DBG> SET WATCH %V2(5:13) 

15.3 Examining and Depositing into Vector Registers 

The following sections explain how to examine and deposit into Uie vector con ro 
registers (VCR, VLR, and VMR) and the vector registers (VO to V15). 

15.3.1 Specifying the Vector Registers and Vector Control Registers 

Thp VAX architecture provides 16 vector registers (VO to V15) and 3 vector 
Th , l rxietprci (VCR VLR and VMR). When referencing any of these registers 
SS—-the following built-in symbols (the mgister name 

preceded by a percent sign (%)): 


Svmboi Description — 

%V0 ... %V15 

Vector registers (VO .. . V15) 

%VCR 

Vector count register (VCR) 

%VLR 

Vector length register (VLR) 

%VMR 

Vector mask register (VMR)____ 


As with all debugger register j — —- 

your program has not declared a symbol with the same name. 

15.3.2 Examining and Depositing into the Vector Count Register 

The vector count register (VCR) specifies the length of the offset vector generated 
by the IOTA instruction. 

The value of VCR is an integer from 0 to 64. By default the debugger treats 
VCR as a longword integer. You can deposit values greater than 64 into VCR, but 
SebugSlTues a diagnostic message that the value is out of bounds in such 

cases. 

The following command sequence shows how to manipulate the value of VCR: 

DBG> EXAMINE %VCR 
0\%VCR: 8 

DBG> DEPOSIT %VCR = 4 
DBG> EXAMINE %VCR 
0\%VCR: 4 
DBG> 

15.3.3 Examining and Depositing into the Vector Length Register 

The vector length register (VLR) limits the highest element of r 

that is tirocessed bv a vector instruction. The value of VLR is an integer irom 
to 64. This value specifies the number of register elements that are processed, 

starting with element 0. 

In the context of a debugging session, the current value 

element of a vector register that you can access with an EXAMINE or lmwau 
debugger command. 
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15.3 Examining and Depositing into Vector Registers 


The following command sequence shows how 
examine different numbers of elements of the 


to manipulate the value of VLR 
vector register Vl: 


DBG> EXAMINE %VLR 
0\%VLR: 4 
DBG> EXAMINE %V1 
0\%V1 


to 


(0): 

12 

(1): 

3 

(2): 

138 

(3): 

51 

DBG> DEPOSIT 

%VLR = 3 

DBG> EXAMINE 

%VLR 

0\%VLR: 3 


DBG> EXAMINE 

%V1 

0\%V1 


(0): 

12 

(1) : 

3 

(2): 

138 


DBG> 


You cannot access a register element outside the range from 0 to VLR-1 In the 
following example, the EXAMINE command specifies element 7 of register Vl 
which is out of bounds (FORTRAN array syntax)- ^ ’ 


DBG> EXAMINE %VLR 
0\%VLR: 3 

DBG> EXAMINE %V1(7) 

^DEBUG-E-VECTSUBRNG, vector register subscript out of bounds 
bounds are 0..2 ' 

DBG> 


By default the debugger treats VLR as a longword integer. You can deposit 
va ues greater than 64 into VLR, but the debugger issues a diagnostic message 
that the value is out of bounds in such cases. message 

15.3.4 Examining and Depositing into the Vector Mask Register 

,Wrnp?° r mask , register (VMR ) specifies a mask (a bit pattern) that a vector 
nstruction uses to operate on only certain elements of a vector register operand 

Cann °‘ 0Perate “ “ *• vSor 

VMR has 64 bits (1 quadword) numbered 0 to 63. Each bit corresponds to an 
element of a vector register. The value of a particular bit (oT^^nTs 

operation^ 6 COrreSp ° nding reglster element * operated on during a masked 


Masked operations are explained in Section 15.4.1 and Section 15.5. This section 
describes how to display and change the value of VMR. 

To examine one or more specific elements (bits) of VMR, use the same technique 
that you use to examine an array variable. (See Section 8.2.3.) Q 

(FORtS^sXx)' the f0 “ 0Wing C ° mmand ^ th< “ b “ 5 ° f VMR is set 


DBG> EXAMINE %VMR(5) 
0\%VMR(5): 1 

DBG> 
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15.3 Examining and Depositing into Vector Registe 


The following command displays the values of bits 4 to 6 of VMR. Bits 4 and 5 
are set, and bit 6 is clear: 

DBG> EXAMINE %VMR(4:6) 

0\%VMR 


DBG> 


(4) 

(5) 

( 6 ) 


1 

1 

0 


Bv default when you examine VMR without specifying subscripts, the debugger 
® sptays the* a“e y of the register as a quadword integer in hex.dec.mal format to 
reduce the size of the output display. For example. 

dbg> examine %vmr 

OUVMR 

(0) : OFFFFFFF FFFFFFFF 

DBG> 

Bv specifying the EXAMINE/BIN %VMR or EXAMINE %VMR(0:63) command, 
you can dTspfay the value of each bit of VMR in a 64-row array format. 

As with an array variable, you can deposit a value into one bit of VMR at a time. 

For example: 

DBG> EXAMINE %VMR(37) 

0\%VMR(37): 1 

DBG> DEPOSIT %VMR(37) = 0 
DBG> EXAMINE %VMR(37) 


0\%VMR(37): 
DBG> 


0 


You can also deposit a quadword integer value into the entire aggregate by using 
the DEPOSIT/QUADWORD command. For example: 

DBG> DEPOSIT/QUADWORD %VMR = %HEX OFFFFF 

DBG> EXAMINE IVMR 

0\%VMR 

(0) : 00000000 000FFFFF 

DBG> 

When specifying an element of VMR in a language expression, remember that 
VMR is an array of bits. You might have to temporarily set the language to one 
that allows bit operations, such as C or BLISS. For example: 

DBG> SET LANGUAGE C 

DBG> S I STJ3 K D0 tfF %VMR[I] == 1 THEN (DEF/VAL K = K + D) 

15 3.5 Examining and Depositing into the Vector Registers (VO to VI5) 

There are 16 vector registers, designated VO to V15. Each of the vector renters 
has 64 elements, numbered 0 to 63, and each element has 64 bits (one quadword). 

To examine one or more elements of a vector register u^ the same technique 
that you use to examine an array variable. (See Section 8.2.3.) The example 
this section use FORTRAN array syntax: 


DBG> EXAMINE %V3 
DBG> EXAMINE %V3(27) 
DBG> EXAMINE %V3(3:14) 
DBG> EXAMINE 


jVO (2), %V3 (1:4) 


[Examine all elements of V3 
[Examine element 27 of V3 
[Examine elements 3 to 14 of V3 
[Examine element 2 of V0 and 
[elements 1 to 4 of V3 
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15.3 Examining and Depositing into Vector Registers 

The va^ of register elements are displayed in an indexed format similar to that 
sed for an array variable. For example, the following command displays the 
values of elements 1 to 3 of register VI: p y me 

DBG> EXAMINE %V1(1:3) 

0\%V1 


( 1 ) 

( 2 ) 

(3) 


3 

138 

51 


DBG> 

id a : range of vector resisters - For exam!>le ' 1116 

DBG> EXAMINE %V0:%V3 
DBG> EXAMINE %V2(7):%V3(12) 

As with an array variable, you can deposit a value into only one element of 
a vector register at a time. For example, the following command deposits the 
integer value 8531 into element 9 of VO: ^ 

DBG> DEPOSIT %V0(9) = 8531 

Hr* ° f the VeCt ° r Iength register (VLR) limits the highest register 
that you can examine or deposit into. (See Section 15.3.3.) Therefore 
the following commands are equivalent: 

DBG> EXAMINE %V1 

DBG> EXAMINE %V1(0:%VLR-1) 


are 


The expression 0:%VLR-1 specifies the range of register elements that 
denoted by the current value of VLR. 

By default the debugger treats each element of a vector register as a longword 
integer and displays the value in the current radix. For example: 

DBG> EXAMINE %V3(27) 

0\%V3(27): 5983 

DBG> DEPOSIT %V3(27) = 3625 
DBG> EXAMINE %V3(27) 

0\%V3(27): 3625 

DBG> 

However, note that a register value that is examined in the context of a vector 
instruction (that is as an instruction operand) is displayed in the data type that 
is appropriate for the instruction (see Section 15.4.1. 

To display the full (quadword) value of an element of a vector register as a 
quadword integer, use the EXAMINE/QUADWORD command. Similarly to 

DEPOSn’/QU^DWORD^ ™ llle ^ “ regiSter e ‘ ement ' the C ° mm * nd 

JnW Spn^ ^ 0f , th ® ° ther type 9 ualifi ers associated with the EXAMINE 
example ° S C ° mmands (f ° r exam P le - /FLOAT) to override the default type. For 

DBG> EXAMINE %V5(2) 

0\%V5(2): 0 

DBG> EXAMINE/D_FLOAT %V5(2) 

0\%V5(2): 0.0000000000000000 

DBG> 
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15.3 Examining and Depositing into Vector Registers 

You can use register symbols in language expressions subject to the relictions 
on using aggregate data structures in languwe expre^ons^&e Section 8.1.5. .) 
For example, the following expression is valid (FORTRAN syntax). 

DBG> EVALUATE %V0(4) .EQ. !V1(4) 

However, the following expression is not valid because more than one register 
element is specified: 

DBG> EVALUATE %V0 .EQ. %V1 

15.4 Examining and Depositing Vector Instructions 

The techniques for manipulating vector instructions include all of those used for 
scalar instructions (described in Section 8.3) and additional techniques specific to 
vector instructions: 

• You can use a screen-mode instruction display to present the scalar and 
vector instructions decoded from the instruction stream of your program. 

• You can execute your program at the vector instruction level by using 
commands such as: 

STEP/VECTOR JNSTRUCTION 
STEP/INSTRUCTION=(opcode/) ... 7) 

SET STEP VECTOR_INSTRUCTION 
SET STEP INSTRUCTION=(opco<fe/) . . 

SET BREAK/VECTORJNSTRUCTION 
SET BREAK/INSTRUCTION =(opcode[, . 

. You can use the EXAMINE/OPERANDS command to display the instruction 
at the current PC value (where execution is paused), induding any operand 
information contained in vector registers. In addition, the /TMASK an 
/FMASK qualifiers enable you to simulate the effect of the vector mask 
register (VMR) or override any masking associated with the examined 
instruction so that you can hide or display specific register elements. 

. You can deposit a vector instruction at a particular memory address in your 
program. 

Whether you are examining or depositing vector instructions, the debugger 
correctly processes the vector instruction qualifiers according to the instructions 
to which they apply. The following table summarizes the functions of these 
qualifiers. See the OpenVMS MACRO and Instruction Set Reference Manual for 
complete information about their use. 


7) 


7) 


Instruction 

Qualifier Description 


/U 

/V 

/M 

/0 

/I 


Enable floating underflow (vector floating-point instructions) 

Enable integer overflow (vector integer instructions) 

Modify intent (VLDjc and VGATH* instructions) 

Perform masked operations only on elements for which the VMR bit is 0 
Perform masked operations only on elements for which the VMR bit is 1 


15-8 







15.4.1 


1 * A _ Deb H99 in 9 Vectorized Programs (VAX Only) 
15.4 Examining and Depositing Vector Instructions 

Examining Vector Instructions and Their Operands 

When you examine a program location that contains a vector instruct,™ th* 

Scfo deCOd K? V inStn,Cli ° n ” d “ andTo^XS their 

MACRO !ST b r f ? rm e lth D the f ° ll0Wing restrictions (see the OpenVMS 
opcoXS Se ‘ Manual for details about instruction 

’ L t ?a e i V mode r “ n °‘ usin * either ™”><»diate or short- 

literal mode, the debugger cannot translate the opcode and therefore 

18 p ay f e instruction and its operands in their vector architectural form 
rather than their MACRO assembler form. arcmtectural torm 

’ diSplayS the ^ruction mnemonic 

this r, ^ than VSMERGEF > VSMERGED, or VSMERGEG In 

cuien^dii ^ iS diSplayed aS 3 quadword integer in th e 

The command EXAMINE/OPERANDS ,%PC enables you to display the 

vouexalTn 31 * * ^ Urren * PC value and its operands. (See Section 8.3.1.) When 
you examine a vector instruction with this command, the values of anv vector 

arfay s^taxh" dlSplayed 38 f ° r an array variable - For example (FORTRAN 


DBG> EXAMINE/OPERANDS 
PROG$MAIN\%LINE 81+19: 
VO contains: 


.%PC 


VSTL VO,W A -572(FP),S A #4 


0\%V0(0) 
0\%V0(1) 
0\%V0(2) 


137445504 

137445504 

137445504 


DBG> 


W A -572 (FP) 2145991456 contains 2 


As with scalar instructions, operand values are displayed in the data type that is 
appropriate for the examined instruction. 

When you use the EXAMINE/OPERANDS command, the display of register 
elements depends on the following factors: 

• The cuirent value of VLR. The highest element of a vector register that is 
operated on (and, therefore, displayed) is limited by the value of VLR. 

Whether the examined instruction is performing a masked operation In 
an unmasked operation, all register elements (up to VLR-1) are displayed 

by the presence of the 71 or 70 in “ 

WADDF/l VO, VI, V2 

J”. f 7™p d ° peration > anl y the elements that correspond to the set or clear 

is /I IT are ? P T, ° n (d6pending on whether tbe instruction qualifier 
is /I or /0, respectively). H 

These concepts are shown in the following two examples, which show an 
unmasked and a masked register-to-register operation, respectively. 

In this example, the examined instruction, WADDF, is performing an unmasked 

rSMayXi CUmmt Va,Ue rfVMB iS irrelev “‘ 0*5 
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15.4 Examining and Depositing Vector instructions 


DBG> EXAMINE IVLR 
0\%VLR: 6 

DBG> EXAMINE %VMR(0:5) 
0\%VMR 


( 0 ) 

( 1 ) 

( 2 ) 

(3) 

(4) 

(5) 


1 

0 

1 

0 

1 

0 


DBG> EXAMINE/OPERANDS 
PROG$MAIN\%LINE 12: 


.%PC 

WADDF V0,V1,V2 


V0 contains: 


0\%V0(0): 

7.0000000 

0\%V0(1): 

7.0000000 

0\%V0 (5): 

7.0000000 

VI contains: 


0\%V1(0): 

4.0000000 

0\%V1(1) : 

4.0000000 

0\%V1(5): 

4.0000000 

V2 contains: 


0\%V2(0): 

5.0000000 

0\%V2(1): 

5.0000000 

0\%V2(5) : 

5.0000000 


DBG> 


In the next example, the same WADDF instruction is performing a masked 
operation. The instruction qualifier /I specifies that elements that match the set 
bits (bit value 1) in VMR are operated on. 


DBG> EXAMINE %VLR 
0\%VLR: 6 

DBG> EXAMINE IVMR(0:5) 
0\%VMR 


( 0 ) 

( 1 ) 

( 2 ) 

(3) 

(4) 

(5) 


1 

0 

1 

0 

1 

0 


dbg> examine/operands 

PROG$MAIN\%LINE 12: 

VO contains: 

o\%vo(0) 

0\%V0(2) 

0\%V0(4) 

VI contains: 

0\%V0(0) 

0\%V0(2) 

0\%V0(4) 

V2 contains: 

o\%vo(0) 

0\%V0(2) 
0\%V0(4) 

DBG> 


. %PC 

WADDF/I V0,V1, V2 

0000000 

0000000 

0000000 


4.0000000 

4.0000000 

4.0000000 

5.0000000 

5.0000000 

5.0000000 
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15.4 Examining and Depositing Vector Instructions 


T Ske A ° P u erati ° n that l0ads data from mem ory to a 
vector regaster. Comments, keyed to the callouts, follow the example. 

DBG> EXAMINE %VLR 
0\%VLR: 6 

DBG> EXAMINE %VMR(0:5) 

0\%VMR 

( 0 ): 1 

( 1 ): 0 

( 2 ): 1 

(3) : 0 

(4) : 1 

(5) : 0 

DBG> EXAMINE/OPERANDS .%PC O 
PROG$MAIN\%LINE 31+12: VLDL/1 ARR+8 #4 VO 

PROG$MAIN\ARR(3) ' " ---■ AKK+8 ' f4 ' vu 


VO contains: 

0UV0(0) 

0\%V0(2) 

0\%V0(4). 

DBG> EXAMINE ARR(1:8) © 


(address 1024) contains 35 

© 


© 

0 


PROG$MAIN\ARR 

(1) 

9 

(2) 

17 

(3) 

35 

(4) 

73 

(5) 

81 

(6) 

6 

(7) 

7 

(8) 

49 


DBG> 

The following comments refer to the callouts in the previous example: 

O The EXAMINE/OPERANDS command shows that a VLDL instruction 
is about to be executed. The instruction will load longword-integer data 

FiXr^lT’ ^ byt6S ’ int ° ^ VO, as shownt 

Whl F + 18 71 ! hows the intents of VO after the instruction 
example) GXeCUted ' Array ARR 1S mdexed 1 to n, not 0 to n-1 (FORTRAN 

0 Slflth Va l U l (#4 l° f thG V J J)L instruc ti° n specifies the number of bytes 
between the start addresses of array elements. 

® instruction operand ARR+8 denotes the start of array element 8 ARRf'ii 

Sr^ M “, RANDS only the ^"(Sy 

ARR that is operated upon (see item ©). y 

0 V e UeS ° f T 1 "" “ d VMR wil1 ««> VLDL instruction to load 

the contend of array elements ARR(3), ARR(5), and ARR(7) into resister 

elements V0(0), V0(2), and V0(4), respectively. The EXAMINE/OPERANDS 
command shows the contents of VO before the instruction has been executed 

© For reference the EXAMINE ARR( 1:8) command displays the full range of 
array elements that are associated with the load operation. 
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15.4 Examining and Depositing Vector Instructions 


Figure 


15-1 Masked Loading of Array Elements from Memory into a Vector 
Register 


Instruction: vldl/1 arr+8,#4,vo 

ARR 


VO (0:5) 



ZK-1937A-GE 

15.4.2 Depositing Vector Instructions 

The techniques for depositing VAX scalar instructions also apply to depositing 
vector instructions (see Section 8.3.2). For example the foUowng command 
deposits a masked WMULF vector instruction at the current PC address. 

DBG> DEPOSIT/INSTRUCTION .%PC = "WMULF/0 V2,V3,V7" 

Note the following information when depositing vector instructions (see the 
OpenVMS MACRO and Instruction Set Reference Manual for details about 
instruction opcodes): 

. The regnum.rw operand of the MxVP and VSYNC instructions is generated 
as a short literal. 

• Do not specify a vector control word when depositing a vector instruction. 

The debugger constructs the vector control word based on the instruction and 
instruction qualifiers, if any, and encodes it using immediate mode. 

• The value of an immediate argument of a VSMERGEx instruction is 
interpreted according to the data type associated with that instruction. 

For example, the src argument for a VSMERGEF instruction is interpreted 
as a Floating value, and so on. For VSMERGE without a type suffix, t 
debugger interprets a literal src operand as a quadword integer in the current 

radix. 
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15.5 Using a Mask When^Sn^ 

5 Instructions* 11 Wh@n Examinin 9 Vector Rasters or 

Section 15.4.1 explains how the command EXAMINE/OPERANDS %Pr rii^i 
Display only certain elements of a vector register or of an array in memory 

' 2SS,t2S? maskmg Hfany) that might be assMiated » 

^mSe « k d by U8ing the '™ ASK ° r / ™ ASK ***** «» 


_ Note 


The remainder of this section describes use of the /TMASK and /FMASK 
qualifiers when examining vector registers. Unless indicated otherwise 

mem~ s alS ° ^ * ~ ° f ' 


The /TMASK qualifier applies the EXAMINE command only to the elements of 

Thl/FMASK reg ! S fi 6r tha V C ° rr f P0nd t0 the set bits ^it value: 1) of the mask 
The /FMASK qualifier applies the EXAMINE command only to the elements that 
correspond to the clear bits (bit value: 0) of the mask. elements that 

The current value of VLR limits the highest element of a vector register that vou 

memoT" 6 ' ^ ° f ^ n °‘ fn 

mUtfMA Tfi <in l he f0rm ° f a mask addreSB «P^ion) with 
tne /1 iviAolv and /t MASK qualifiers. For more information: 


IS 


Section 15.5.1 describes using these qualifiers with the default mask, which 

VMR°as \he mask. CribeS qUaUfierS with SOme arbit ^ ^ce of 

Section 15.5.3 describes using these qualifiers with a mask other than VMR. 

Using VMR as the Default Mask 

EMINE/FMaSt? 0 n0t SP !, Ci S A amask with the EXAMINE/TMASK or 
EXAMINE/FMASK command, VMR is used as the mask. That is the EXAMINE 

command !s ap phed only to the elements of the vector register that co ^nd to 
the set bits (in the case of /TMASK) or clear bits (in the case of /FMASK) of ^IR 

M^ng iTof ‘ eS ’ VLE haS ^ Va ‘ Ue 6 a " d VMK0:VLK ' 1 > ^ 
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I's.^Usi'ng ^^askWhe^Ex^minin^VectorRegisters or Instructions 


DBG> EXAMINE %VMR(0:%VLR 1) 

0\%VMR 

( 0 ): 1 

( 1 ) : 0 

( 2 ): 1 

( 3 ): 0 

(4) : 1 

( 5 ) : 0 

DBG> 

The following command displays the value of V3 without using a mask. All 
elements of V3 from 0 to VLR-1 are displayed: 

dbg> EXAMINE %V3 
0\%V3 


( 0 ) 

( 1 ) 

( 2 ) 

(3) 

(4) 

(5) 


17 

138 

3 

9 

51 

252 


DBG> 

The following command displays the elements of V3 (in the range from 0 to 
VLR-1) for which VMR(i) has the value 1: 

dbg> EXAMINE/TMASK %V3 
0\%V3 


( 0 ) 

( 2 ) 

(4) 


17 

3 

51 


DBG> 

The following command displays the elements of V3 (in the range from 0 to 
VLR-1) for which VMR(i) has the value 0: 

dbg> EXAMINE/FMASK %V3 
0\%V3 


( 1 ) 

(3) 

(5) 


138 

9 

252 


DBG> 

command displays the register-operand elements (in the range fro 
for which VMR(i) has the value 0: 

dbg> examine/operands/fmask .%pc 
PROG$MAIN\%LINE 341+16: WEQLL VO,VI 
VO contains: 

0\%V0(1): 0 

0\%V0 (3) : 

0\%V0(5): 


VI contains: 

0\%V1(1): 
0\%V1(3): 
0\%V1 (5) 

DBG> 


0 

0 

0 

0 
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15.5 Using a Mas, When°SL^ 

15.5.2 Using a Slice of VMR as the Mask 

Iimits the number of register element 

DBG> EXAMINE %VLR 
0\%VLR: 12 

DBG> EXAMINE %VMR(3:5) 

0\%VMR 


(3) 

(4) 

(5) 


1 

1 

1 


DBG> EXAMINE/TMASK=(%VMR(3:5)) %V0(3:10) 

o\%vo 

(3) : 9 

(4) : 51 

(5) : 252 

DBG> 

Use parentheses when specifying a mask with the /TMASK qualifier. 

The lowest specified element of the mask is applied to the lowest specified 

DBG> EXAMINE %VLR 
0\%VLR: 12 

DBG> EXAMINE %VMR(4:7) 

OUVMR 
(4) 


(5) 

( 6 ) 
(7) 


1 

0 

1 

1 


DBG> EXAMINE/TMASK=(%VMR(4:7)) %V0(3:10) 

oDEBUG I MASKMISMATCH, mask/target subscripts do not match 

0\%V0 displaying mask 

%VMR(4) : 1 

%V0(3): 9 

%VMR(6) : 1 

%V0 (5): 252 

%VMR(7) : 1 

%V0(6): 56 

DBG> 

15.5.3 Using a Mask Other than VMR 

the mask subject to the following conventions: 

If the mask address expression denotes a Boolean array, its values are used 

r? e „ maSk m the S , ame baS1C way that VMR is used in the default case In 

B0 ° L - ARR ’ “ -y vaHaHet'J" 
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dbg> examine %vlr 

0\%VLR: 6 

dbg> examine bool_arr 

PROG$MAIN\BOOL_ARR 


( 0 ) 

( 1 ) 

( 2 ) 

(3) 


0 

0 

1 

0 


DBG> EXAMINE/FMASK= (BOOL_ARR) ■sVO 

%DEBUG-I-MASKNOTVMR, mask used is not %VMR, displaying 
specified mask 

0\%V0 

BOOL_ARR(0): 0 

%V0 (0) : 13 

BOOL_ARR(l): 0 

%V0 (1) : 138 

BOOL_ARR(3): 0 

%V0(3): 9 

DBG> 

As shown in the example, when you use a mask other than VMR, the 
debugger displays both the mask elements and the register elements that a 

operated on and issues a message. 

• If the mask address expression denotes a non-Boolean array, the least 

Ji tot Jof each array element la used as the mask for the corresponding 
element of the register. 

• If the mask address expression denotes a Boolean scalar type, its value is 
used as the mask for the first element of the register. No other elements are 
“SiSi In So following example, BOOL.VAE, a single-element Boolean 

variable, is used as the mask: 

dbg> examine bool_var 

PROG$MAIN\BOOL_VAR: 1 

DBG> EXAMINE/TMASK=(BOOL_VAR) %V0 , 

%DEBUG-I-MASKNOTVMR, mask used is not %VMR, displaying 
specified mask 

0\%V0 

BOOL_VAR: 1 

%V0(0): 13 

DBG> 

• If the mask address expression denotes any other type, its least significant 
bit value is used as the mask for the first element of the register. No other 
elements are examined. 

. The number of mask elements specified limits the number of renter elements 
that you can examine, as when the mask is VMR (see Section 15.5.2). 

. For a multielement mask, the lowest specified element ofthemask Mapped 
to the lowest specified element of the register, as when the mask is VMR (see 

Section 15.5.2). 

15.6 Examining Composite Vector Address Expressions 

When using the EXAMINE command, you can specify various forms of composite 
a^ress^xpressions—expressions that include byte offsets from a given address. 
For example if X is an integer variable, the following EXAMINE command 
displays the Value currently stored at the memory location that is 6 bytes beyond 

the address of X: 
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15.6 Examining Composite Vector Address Expressions 

dbg> EXAMINE X + 6 
MOD3\X+6: 274903 

DBG> 

%£££££: «aZ“ ess 

DBG> EXAMINE %VLR 
0\%VLR: 5 

DBG> EXAMINE/OPERANDS .%PC O 
PR0G1$MAIN\ILINE 9+32: VSCATL 
V7 contains: 

0\%V7(0): 11 0 

0\%V7(1); 13 

0\%V7(2): 15 

0\%V7(3): 17 

0\%V7(4): 19 

V9 contains| R1 ^ p ^OGi$MAIN\ARRX(1, (address 1820, contains 0 0 

0 O 

8 

16 
24 
32 


V7,W A -804 (Rll) ,V9 


0\%V9(0) 

0\%V9(1) 

0\%V9(2) 

0\%V9(3) 

0\%V9 (4): 

DBG> SHOW SYMBOL/TYPE ARRX v 
data PR0G1$MAIN\ARRX 

array descriptor type, 1 dimension, bounds: [1:2001 size- son hvtae 
cell type: atomic type, longword integer size- 4 hv+ff ° Y 
DBG> EXAMINE ARRX(l) + .%V9(0:%VLR-J )6 7 

. 0 

0 
0 
0 
0 


- 

PR0G1$MAIN\ARRX(1) 
PR0G1$MAIN\ARRX(3) 
PR0G1$MAIN\ARRX(5) 
PR0G1$MAIN\ARRX(7) 
PR0G1$MAIN\ARRX(9): 
DBG> STEP/INSTRUCTION 


stepped to PR0G1$MAIN\ILINE 9+40: MOVZBL I A #64 AP 
DBG> EXAMINE ARRX(l) + .%V9(0:%VLR-1, © ' 

PR0G1$MAIN\ARRX(1): n ' W 

13 
15 
17 
19 


PR0G1$MAIN\ARRX(3) 

PR0G1$MAIN\ARRX(5) 

PR0G1$MAIN\ARRX(7) 

PR0G1$MAIN\ARRX(9) 

DBG> 

The following comments refer to the callouts in the previous example: 

® ? 6 fXAM^/OPEHANDS command shows that a VSCATL instruction is 
about to be executed. The instruction will transfer longword-integer (4-byte) 
data from register V7 into memory locations. These locations are determSed 
by adding offset values, contained in register V9, to a base address. 

Register V7 contains the longword-integer values to be transferred to memory. 

The base address specified as an operand to the VSCATL instruction is 
symbolized as ARRX(1), which denotes element 1 of array ARRX. 

from the base address ' in bytes ' of each tarset 

“ mmand indiCateS tha ‘ iS “ ° f 


0 

0 

O 
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Examining Composite Vector Address Expressions 

0 The EXAMINE command display In 

1 sss 

O The STEP/INSTRUCTION command exemtes the VS C AT L instruction and 
suspends execution at the next instruction, M 
0 As in item the EXAMINE command displays the values of the target 
IX elements in memory. Now the contents of memory show that the 
values have been transferred from register V7. 

The next example shows how to specify a more complex vector address expression 
with the EXAMINE command. 

Assume that array ARRZ has contiguous quadword-integer (8-byte) el fnents. 

The fourth EXAMINE command in the example displays the values of vecto 
dem"~ starting at element AERZtl). As in 

the debugger symbolizes the locations of vector elements in term s of the an y 
Aments V location of successive vector elements relate, to ARRZd is 
computed by adding the values contained in registers VI and V3 to specily a 
combined offset for a particular element. The order in which vector elements a re 
displayed is determined by cycling through all the values in the last spea 
register (V3(0:2)) for each value in the first specified register ( ). 

example, the values of all vector elements are 0. 


dbg> examine 

0\%VLR: 4 
DBG> EXAMINE 
0\%V1 

( 0 ) 

( 1 ) 

( 2 ) 

(3) 

dbg> examine 

0\%V1 


%VLR 


%V1 


0 

4 

8 

12 


%V3 


0 


16 
24 
ARRZ(l) 


( 0 ): 

( 1 ): 

( 2 ): 

(3): 

dbg> examine 

PR0G4$MAIN\ARRZ(1) 
PROG4$MAIN\ARRZ (2) 
PR0G4$MAIN\ARRZ(3) 
PR0G4$MAIN\ARRZ(1)+4 
PR0G4$MAIN\ARRZ (2) +4 
PR0G4$MAIN\ARRZ(3)+4 
PR0G4$MAIN\ARRZ (2) 
PR0G4$MAIN\ARRZ(3) 
PR0G4$MAIN\ARRZ(4) 
PR0G4$MAIN\ARRZ (2) +4 
PR0G4$MAIN\ARRZ(3)+4 
PR0G4$MAIN\ARRZ(4) +4 
DBG> 


.%V1(0:3) + .%V3(0:2) 
ARRZ(1) +0+0 
ARRZ(1)+0+8 
ARRZ(1)+0+16 
! ARRZ(1)+4+0 
! ARRZ(1)+4+8 
! ARRZ(1)+4+16 


0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 


ARRZ(1)+8+0 
ARRZ(1)+8+8 
ARRZ(1)+8+16 
ARRZ(1)+12+0 
ARRZ(1)+12+8 
ARRZ(1)+12+16 
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15.7 Displaying the Results of Vector Floating-Point Exoeptfons 

Displaying the Results of Vector Floating-Point Exceptions 

as shown in Section 15 8 The foil eXCeptl0 , n ^ at 1S stlU Pending delivery, 
causea a floa 


DBG> EXAMINE/FLOAT 
0\%V5 


DBG> 


( 0 ) 

( 1 ) 

( 2 ) 

(3) 


297.2800 

87.41499 

1?3 6 8650 ° Perand ' enC0d6d 35 fl ° ating divide b Y zero 





Controlling Scalar-Vector Synchronization 


To achieve high performance, the VAX scalar and vector processors operate 
concurrently as much as possible. The scalar processor passes any Sector 
instructions to the vector processor and then continues executing Scalar 
instructions while the vector processor executes vector instructions. 

In some cases, the operation of the two processors must be synchronized to 

SraC MS™ C P aS a vs™c‘ S .h % USi ” g T Chr0niZing instn ‘ cti °" s <"><* a* 

uo ’ 1 ' dbYNC > and VSYNC, the program forces certain operations to comnlete 
before other* are initiated. See the OpenVMS MACRO and InstrucZnZ 

^ f °- ^ ‘“emotions anfsTalttecior 

ml h nil! r ur hSS been vectorized b y the compiler (for example, the DEC Fortran 
pder), the necessary synchronizing instructions are automatically generated 

wever, CRO programmers need to code synchronizing instructions explicitly. 

By default, the debugger does not force scalar-vector synchronization durimr 
program execution except for its own internal purposes The pro^am executes 
2 ^ running without debugger control, and synchronization Ts controlled 

set is established by the 
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15.8 Controlling Scalar-Vector Synchronization 

For example: 

. An exception caused by a vector instruction might be pending delivery. 

• An oneration that transfers data between vector registers and scalar memory 
W ht not be completed. Therefore, examining the contents of memory 
vector registers might yield unpredictable results. 

which execution is paused. The effect is as follows. 

. . • +Vl „ t wfl< , cau sed bv a vector instruction and was still pending 

delivery^ immediately delivered. Forcing the delivery of a pending exception 
triggers an exception breakpoint or tracepoint (if one was set) or invokes an 
exception handler (if one is available at that location in the program). 

. Any read or write operation between vector registers and either the general 
registers or memory is completed immediately—that is, any vec or mem 
instruction that was still being executed completes execution. 

The following MACRO example shows the effect of the SYNCHRONIZE 

VECTOR_MODE command: 

DBG> STEP O 

stepped to .MAIN.\SUB\'6LINE 99 
99: WDIVD VI, V0,V2 

DBG> STEP © 

stepped to ,MAIN.\SUB\%LINE 100 
100: CLRL R0 

DBG> EXAMINE/FLOAT %V2 © 

0\%V2 


[ 0 ] 

[ 1 ] 

[ 2 ] 


Reserved operand, encoded as floating divide by zero 
247.2450 


DBG> SYNCHRONIZE VECTOR_MODE © mmar w=nn000002 

o,q Y q TFM _p_vARTTH, vector arithmetic fault, summary 000UUUU , 

.SYSTEM F VARITH, pc=000002E1( p SL=03 C000 0 

break on unhandled exception preceding ,MAIN.\SUB\%LINE 100 
100: CLRL R0 

DBG> 

The following comments refer to the callouts in the previous example: 

O This STEP command suspends program execution on line 99 just before 
a WDIVD instruction is executed. Assume that, in this examp e, 
instruction will trigger a floating-point divide-by-zero exception. 

@ This STEP command executes the WDIVD instruction. However, the 
exception is not delivered at this point in the execution of the progra . 

a The EXAMINE/FLOAT command displays a decoded exception message m 
element 1 of the destination register, V2 (see Section 15.7). This confirm 
that a floating-point divide-by-zero exception was triggered and is pending 

delivery. 
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15.8 Controlling Scalar-Vector Synchronization 


0 E&f™S? 01 ™ 1 ^CTOR-MODE command forces the immediate 
delivery of the pending vector exception. (You might obtain a different set 

lagnos ic messages if your program were using the WIEF rather than 
vector processor hardware.) ratner than 

An alternative to using the SYNCHRONIZE VECTOR MODF • * 

M9TOP instruction after every vector instruction and, in addition an 

S^ 1 f n V eCt ° r mStrUCti0n that memS TOs 

“ d w,th the "*» ““ a- * 

Any exception that was caused by a vector instruction is delivered before 

excenf Xt T ^ mStructlon 18 execute d. Forcing the delivery of a pending 
exception triggers an exception breakpoint or tracepoint (if one was set/ 

pro^r an eXCePti0n handler <if ° ne iS at that locattataL 

• Any read or write operation between vector registers and either the general 
executed. 0 ' mem017 ‘ S before th * ? 

mSSSr* 8h °T the effeCt of the SET VECTOR.MODE 
SYNCHRONIZED command on the same instruction stream that was used 
in the previous example: a 

DBG> SHOW VECT0R_M0DE 

Vector mode is nonsynchronized 

DBG> SET VECT0R_M0DE SYNCHRONIZED O 

DBG> SHOW VECT0R_M0DE 

Vector mode is synchronized 

DBG> STEP © 

stepped to .MAIN.\SUB\%LINE 99 
99: WDIVD V1,V0,V2 

DBG> STEP © 

%SYSTEM-F-VARITH, vector arithmetic fault, summary=00000002, 
mask=00000004, PC=000002E1, PSL=03C00010 
inn?" unhandled exce Ption preceding .MAIN.\SOB\%LINE 100 

DBG> 

The following comments refer to the callouts in the previous example: 

O The command SET VECTOR_MODE SYNCHRONIZED causes the debugger 
to force automatic synchronization between the scalar and vector processors 
whenever a vector instruction is executed. processors 

^ VVDmfL^Tnd.suspends program execution on line 99 just before a 
,, • IV ? ” t ctl0n 1S executed - Assume that, as in the previous example 

he instruction will tngger a floating-point divide-by-zero exception. 

© This STEP command executes the WDIVD instruction, which triggers 
the exception. The vector exception is delivered immediately because the 
debugger is being operated in synchronized vector mode. 

s^5^ I ^«? w T !E ^ CT0IUtf0DE and SET vector.mode 

C ° mmandS “ ionization- 
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15.9 Calling Routines that Might Affect the Program s Vector State 


15.9 Calling Routines that Might Affect the Program’s Vector State 

_ nm a mrr' o-naVilp VOll to 


IVJ IIWM 1 ..—- w 114 . 

The CALL command’s /[NOISAVE.VECTOR.STATE 9^™ 10 

control whether the current state of the vector processor is saved and 
restored when a routine is called. 


The state of the VAX vector processor comprises the following: 

• The values of the vector registers and vector control registers 
. Any vector exception (an exception caused by the execution of a vector 
instruction) that might be pending delivery 
When you use the CALL command to execute a routine, execution of the routine 
might change the state of the vector processor as follows: 

. By changing the values of vector registers or vector control registers 

By causing a vector exception 


By causing the delivery of a vector exception that was pending when the 
CALL command was entered 


The CALL/SAVE VECTOR STATE command specifies that the state of the vector 
^stt that exists before the CALL command is entered be restored by the 
debugger after the called routine has completed execution. This ensures that, 
after the called routine has completed execution: 


Any vector exception that was pending delivery before the CALL command 
was entered is still pending delivery 


No vector exception that was triggered during the routine call is still pending 
delivery 


The values of the vector registers are identical to their values before the 
CALL command was entered 


The CALL/NOSAVE VECTOR STATE command, which is the default, specifies 
That th^te of tevector processor that exists before the CALL command is 
entered is not restored by the debugger after the called routine has completed 
execution. In this case, the state of the vector processor after the routine call 
depends on the effect (if any) of the called routine. 


Ucpciiuo WAX V--*/ ' 

The /rNO]SAVE_VECTOR_STATE qualifiers have no effect on the VAX general 
(scalar) registers. The values of these registers are always saved and restored 
when you execute a routine with the CALL command. 


15.10 Displaying Vector Register Data in Screen Mode 

_ . « i i 1 — — X. v»I ^ /\ Cl 1 


In screen mode, a register display shows the current values of the VAX general 
registers (see Section 11.2.5). 


ICglotuio -—- 

To display data contained in vector registers or vector control registers in screen 
mode, use a DO display (see Section 11.6.1). 


For example, the following command creates a DO d';fARTlSi ed a™3ax) at 
shows the contents of elements 4 to 7 of register V2 (FORTRAN array syntax;. 
The display is automatically updated whenever the debugger gams control from 

your program. 


DBG> DISPLAY V2_DISP AT RQ2 DO (EXAMINE %V2(4:7)] 
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Debugging Tasking Programs 


This chapter describes features of the debugger that are specific to tasking 
programs (a so called multithread programs). Tasking programs consist of 
multiple tasks, or threads, executing concurrently in a single process These 
programs include the following: 

Programs written in any language that use DECthreads or POSEX 1003 lb 
services. 

Programs that use language-specific tasking services (services provided 
directly by the language). Currently, Ada is the only language with built-in 
tasking services that the debugger supports. 

Within the debugger, the term task denotes such a flow of control regardless of 

the language or implementation. The debugger’s tasking support applies to all 
such programs. 

f” ^'1 cbapter ’ f ny DECt hreads-specific or language-specific information is 
identified as such. Section 16.1 provides a cross-reference between DECthreads 
terminology and Ada tasking terminology. 

The features described in this chapter enable you to perform functions such as: 

• Displaying task information 

• Modifying task characteristics to control task execution, priority state 
transitions, and so on 

• Monitoring task-specific events and state transitions 

When using these features, remember that the debugger might alter the 
behavior of a tasking program from run to run. For example, while you are 
suspending execution of the currently active task at a breakpoint, the delivery 
of an asynchronous system trap (AST) or a POSEX signal as some input/output 

(I/O) completes might make some other task eligible to run as soon as you allow 
execution to continue. J 


f ° T r%Zl inf °/ mati0n about DE Cthreads or POSIX threads, see the Guide 
to DECthreads. For more information about Ada tasks, see the DEC Ada 
documentation. 


The debugging of multiprocess programs (programs that 
process) is described in Chapter 14. 


run in more than one 


16-1 





Debugging Tasking Programs 

16.1 Comparison of DECthreads and Ada Terminology 


16.1 Comparison of DECthreads and Ada Terminology 

Table 16-1 compares DECthreads and Ada terminology and concepts. 


Table 16-1 Comparison of DECthreads and Ada Terminology 


DECthreads Terminology 

Ada Terminology 

Description 

Thread 

Task 

The flow of control within a 

process 

Thread object 

Task object 

The data item that represents 
the flow of control 

Object name or expression 

Task name or expression 

The data item that represents 
the flow of control 

Start routine 

Task body 

The code that is executed by the 
flow of control 

Not applicable 

Master task 

A parent flow of control 

Not applicable 

Dependent task 

A child flow of control that is 
controlled by some parent 

Synchronization object 
(mutex, condition variable) 

Rendezvous construct 
such as an entry call or 
accept statement 

Method of synchronizing flows 
of control 

Scheduling policy and 
scheduling priority 

Task priority 

Method of scheduling execution 

Method of canceling a flow of 
control 

Alert operation 

Abort statement 

Thread state 

Task state 

Execution state (waiting, ready, 
running, terminated) 

Thread creation attribute 
(priority, scheduling policy, 
and so on) 

Pragma 

Attributes of the parallel entity 


16.2 Sample Tasking Programs 

The following sections present sample tasking programs with common errors that 
you might encounter when debugging tasking programs: 

• Section 16.2.1 describes a C program that uses DECthreads services 

• Section 16.2.2 describes an Ada program that uses the built-m Ada tasking 
services 


Some other examples in this chapter are derived from these programs. 

16.2.1 Sample C Multithread Program 

Example 16-1 is a multithread C program that shows incorrect use of condition 
variables, which results in blocking. 

Explanatory notes are included after the example. Following these notes are 
instructions showing how to use the debugger to diagnose the blocking y 
controlling the relative execution of the threads. 

In Example 16-1, the initial thread creates two worker threads that do some 
computational work. After the worker threads are created a SHOW TASK/ALL 
command will show three tasks, each corresponding to a thread (Section lb.4 
explains how to use the SHOW TASK command). 
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16.2 Sample Tasking Programs 

Ss K tosk IDs/suchaSsKW eXeCUteS fr ° m main °' <SeCti ° n 16M 
• %TASK 2 and %TASK 3 are the worker threads. 

the'workers’ path itae^lSM^The P °"' t <a . c °” diaon woit) has >>“ n Placed in 
codej^ht islncorrect^ograrnroing*ant^^nws^e^correc^ 


Example 16-1 Sample C Multithread Program 


3777 

3778 

3779 

3780 

3781 

3782 

3783 

3784 

3785 

3786 

3787 

3788 
3799 

3790 

3791 

3792 

3793 

3794 

3795 

3796 
3787 

3798 

3799 

3800 

3801 

3802 

3803 

3804 

3805 

3806 

3807 

3808 

3809 

3810 

3811 

3812 

3813 

3814 

3815 

3816 

3817 

3818 


/* DEFINES */ 

♦define NUM_WORKERS 2 


/* Number of worker threads 


/* MACROS 

♦define check(status,string) \ 

if (status == -l) perror (string); \ 

/* GLOBALS 
int 

pthread_mutex_t 
pthread_cond_t 
pthreadjnutex t 


cv_predl; 
cvjnutex; 
cv; 

printjrnitex; 

/* ROUTINES 

static pthread_startroutine t 
worker_routine (pthread_addr_t 

main () 

{ 

pthread_t 
int 
int 
int 
int 


*/ 

/* Condition Variable predicate */ 
/* Condition Variable mutex */ 


/* Condition Variable 
/* Print mutex 


*/ 

*/ 


arg) ; 


threads[NUM_WORKERS]; 

status; 

exit; 

result; 

i; 


/* Worker threads 
/* Return statuses 
/* Join exit status 
/* Join result value 
/* Loop index 


*/ 

*/ 

*/ 

*/ 

*/ 


/* Initialize mutexes 

/* Initialize condition variable */ 

check S (statuq 63 " -C ° nd—(iCV ' P thread _condattr default); 
cneck (status, cv condition mit bad status"); ~ 

/ Initialize condition variable predicate 
cv_predl = 1; 


V 


/* Create worker threads 
for (i = 0; i < NUM_WORKERS; 
status = pthread_create ( 
&threads[i 


i++) { 


(continued on next page) 
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Example 16-1 (Cont.) Sample C Multithread Program 

pthread_attr_default, 
worker_routine, 

0 ); 

check (status, "threads create bad status") 


3819 

3820 

3821 

3822 

3823 

3824 

3825 

3826 

3827 

3828 

3829 

3830 

3831 

3832 

3833 

3834 

3835 

3836 

3837 

3838 

3839 

3840 

3841 

3842 

3843 

3844 

3845 

3846 

3847 

3848 

3849 

3850 

3851 

3852 

3853 

3854 

3855 

3856 

3857 

3858 

3859 

3860 

3861 

3862 

3863 

3864 

3865 

3866 

3867 

3868 

3869 

3870 

3871 

3872 

3873 

3874 

3875 

3876 

3877 

3878 

3879 


} 


/* Set cv_predl to false; 


do this inside the lock to insure visibility. 


*/ 


status = pthread_mutex_lock (Scvjnutex), 
check (status, "cvjnutex lock bad status ); 

cv_predl = 0; 

status = pthread mutex_unlock (scvjnutex); 
check (status, "cvjnutex unlock bad status ); 

/* Broadcast. */ 

status = pthread_cond_broadcast (&cv); 
check (status, "cv broadcast bad status ); 


0 


*/ 


/* Attempt to join both of the worker threads, 
for (i = 0; i < NUM WORKERS; i++) ( . ,, 

exit = pthreadJoin (threads [i], (pthread_addr_t*) (.result), 

check (exit, "threads join bad status"); 

} 


static pthread_startroutine_t 
worker_routine(arg) 

pthread_addr_t arg; 


© 


( 

int 

int 

int 

int 


sum; 

iterations; 
count; 
status; 


L D “i“«tioiri1-°i?eratio„ S < 10001,- < 

for (count = 1; count < 10001; count++) { 
sum = sum + count; 

} 

} 

/* Printf may not be reentrant, so allow 1 thread at a time */ 

status = pthread_mutex_lock (Sprint jnutex);^ 
check (status, "printjnutex lock bad status ); 
printf (" The sum is %d \n", sum); 
status = pthread_mutex_unlock (Sprint jnutex); 
check (status, "printjnutex unlock bad status ); 

/* Lock the mutex associated with this condition variable. pthread_cond_wait will */ 
/* iSoc^ the mutex if the thread blocks on the condition variable. 

status = pthreadjnutex_lock (&cvjnutex); ^ 
check (status, "cvjnutex lock bad status ); 

/* 1" th. next . th. corxect “a.tfd SthThe 

3?ioSV.°Ubl“ ThS Sould guard against condition uaitin, on a condition 


V 

V 

V 


(continued on next page) 
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Example 16-1 (Cont.) Sample C Multithread Program 


3880 

3881 

3882 

3883 

3884 

3885 

3886 

3887 

3888 
3888 

3890 

3891 

3892 

3893 

3894 

3895 

3896 

3897 

3898 

3899 

3900 

3901 

3902 

3903 


/* 

/* 

/* 

/* 

/* 

/* 

/* 

/* 

/* 

/* 

/* 

/* 


ups. Execution m would V resume a when e the b thread S ^ UP °k' aS WeU aS spuriolJS wake 
false. The call »o„ld l"k fiS Sls“ "° ke ” '* the predicate is 

while (cv_predl) { 

S ^ at . US , = pt ^ read - cond - wait (Scv, &CV mutex)- 
j check (status ' "cv condition wait bad status"); 

Ja|a r »p , SL C 1t 1 's£ul U d e n d ot ln ( ™!c f ° U f ,in9 K COde ' ■*«* • thread to 

should one of the worker threads here. 0 ' be0 °" e per " aMntl y blocked, as 


status- pthread_cond_wait (&cv, &cv mutex)• A 

check (status, "cv condition wait bad status"); 

/* " ait ' “* r0U “" e ldtS 30 Of the „ute„, hut 

status = pthread_mutex_unlock (scv mutex); 
check (status, "cv_mutex unlock bad status"); 

return (int)arg; 


*/ 

*/ 

*/ 

*/ 

*/ 

*/ 

*/ 

*/ 

*/ 

*/ 

*/ 

*/ 


*/ 

*/ 


Key to Example 16-1: 

0 Sad bvarthf'r 8 "* 8 °n main < ) initiaKze synchronisation objects 
used by the threads, as well as the predicate that is to be associated with 

defeat att°h? na T? The / ynchronization objects are initialized with the 

tS thaUslon 6 T n° n VariaWe PrediCate is initi abzed such that a 

a SH0™°S°X“ “ ‘ WS P ° mt ta ‘ he "• 

© The worker threads %TASK 2 and %TASK 3 are created. Here the created 
,/ eads exe ^ e tbe same start routine (worker.routine) and can also reuse 

thread^Ds Th°^h re d d_Create With 3 Slight change to store the different 
3 h ID Th th ! eads are Created usin S the default attributes and are 
passed an argument that is not used in this example. 


© 


e predicate associated with the condition variable is cleared in preparation 
o broadcast. This ensures that any thread awaking off the condition variable 
as received a valid wake-up and not a spurious one. Clearing the predicate 
also prevents any new arrivals from waiting on the condition variable because 
t has been broadcast or signaled upon. (The desired effect depends on correct 

cas^n tS" e ex U ampW C ° nditi ° n W “‘ at ' ine 3893 ’ Which is not the 

The initial thread issues the broadcast call almost immediately, so that none 
of the worker threads should yet be at the condition wait. A broadcast should 
wake any threads currently waiting on the condition variable. 

As the programmer, you should ensure that a broadcast is seen bv either hv 
ensurmg that all threads are waiting on the condition variaMe at fte Hme 
broadcast or ensuring that an associated predicate is used to flag that the 
“on" h " —s have been 
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Example 16-2 (Cont.) Sample Ada Tasking Program 


36 

37 

38 

39 

40 

41 

42 

43 

44 

45 

46 

47 

48 

49 

50 

51 

52 

53 

54 

55 

56 

57 

58 

59 

60 
61 
62 

63 

64 

65 

66 

67 

68 

69 

70 

71 

72 

73 

74 

75 

76 

77 

78 

79 

80 
81 
82 


task body CHILD is 
begin 

FATHER_TYPE. BOGUS; 
end CHILD; 


begin 


— Deadlocks on call to its parent 

— (parent does not have an accept 

— statement for entry BOGUS). Whenever 

— a task-type name (here, FATHER_TYPE) 

— is used within a task body, the 

— name designates the task currently 

— executing the body. 

(of FATHER_TYPE body) 


•IT 


aCC Bm! TART --°Main program is waiting for this rendezvous to 

— complete; CHILD is suspended when it calls the 

— entry BOGUS. 

null; 

end START; 

PUT LINE ("FATHER is now active and"); © 

PUT - LINE("is going to rendezvous with main program. ), 

for I in 1..2 loop 
select 

arreot RENDEZVOUS do I1X . 

PUT LINE ("FATHER now in rendezvous with main program ), 

end RENDEZVOUS; 
or 

terminate; 
end select; 

if I = 2 then 

raise SOME_ERROR; 
end if; 
end loop; 

exception 

W ^ e BREAK* — CHILD is suspended on entry call to BOGUS. 

— Main program is going to delay while FATHER 
— terminates. 

— MOTHER is ready to begin executing. 

BREAK; 0 —' CHILD is now abnormal due to the abort statement. 

raise; — SOME_ERROR exception terminates FATHER, 
end FATHER_TYPE; 


(continued on next page) 
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Example 16-2 (Cont.) Sample Ada Tasking Program 

begin — (of TASK_EXAMPLE) © 


declare 

task MOTHER is Q 
entry START; 
pragma PRIORITY (6); 
end MOTHER; 

task body MOTHER is 
begin 

accept START; 


BREAK; 


null; 

end MOTHER; 
begin © 


83 

84 

85 

86 

87 

88 

89 

90 

91 

92 

93 

94 

95 

96 

97 

98 

99 
100 
101 
102 

103 

104 

105 

106 

107 

108 

109 

110 
111 
112 

113 

114 

115 

116 

117 

118 

119 

120 
121 
122 

123 

124 

125 

126 

127 

128 

129 end; 

130 end TASK EXAMPLE; 


At this point, the main program is waiting for 

"" ^L^ pendents (FATHER and MOTHER) to terminate. 
FATHER is terminated. 


BREAK; — FATHER is suspended at accept start. 

— CHILD is suspended in its deadlock. 

— MOTHER has activated and ready to becrin exemtina 
FATHER.START; © y g executing. 

BREAK; - FATHER is suspended at its 'select or terminate' 

— statement. 


FATHER.RENDEZVOUS; 

FATHER.RENDE ZVOUS; © 

loop © 

This loop causes the main program to busy wait 
for the termination of FATHER, so that FATHER 
can be observed in its terminated state 
if FATHER'TERMINATED then 
exit; 
end if; 
delay 1.0; 
end loop; 

BREAK; — FATHER has terminated by now with the unhandled 
exception SOME_ERROR. CHILD no longer exists 

” !^n e . itS master (FATHER > has terminated. Task 
— MOTHER is ready. 

MOTHER.START; © 

The main program enters a wait-for-dependents state, 

- so that MOTHER can finish executing. 


Key to Example 16-2: 

° mwi? 11 ° f the Ada libraiy packages are elaborated (in this case, TEXT 
IO) the mam program is automatically called and begins to elaborate its 
declarative part (lines 18 through 82). 

® feSmrnl 2) a m^ y n f T T ^ n,n ’ the exampIe uses no time sUcin « (see 

section 16.5.2). The 0.0 value for the pragma TIME_SLICE documents that 
he procedure TASK_EXAMPLE needs to have time slicing disabled. 

°n VAX processors, time slicing is disabled if the pragma TIME SLICE is 
omitted or is specified with a value of 0.0. ♦ 
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Alpha 


On Alpha processors, pragma TIME.SLICE (0.0) must be used to disable time 
slicing. ♦ 

0 Task object FATHER is elaborated, and a task designated %TASK 2 is 
created FATHER has no pragma PRIORITY, and thus assumes a defau 
nrioritv. FATHER (%TASK 2) is created in a suspended state and is not 
activated until the beginning of the statement part of the mmn program l me 
83), in accordance with Ada rules. The elaboratron of th< 

29 through 81 defines the statements that tasks of type FATHER.! YPE will 

ex6cute. 

O Task FATHER declares a single task named CHILD (line 32). A single task 
represents both a task object and an anonymous task type. Task CHILD is 
not created or activated until FATHER is activated. 

0 The only source of asynchronous system traps (ASTs) is this senes of TEXT_ 
IO.PUT_LINE statements (I/O completion delivers ASTs). 

0 The task FATHER is activated while the main program waits. FATHER has 
no pragma PRIORITY and this assumes a default pnonty of 7. (See the 
DEC Ada Run-Time Reference Manual for the rules about default prion i .) 
FATHER’S activation consists of the elaboration of lines 29 through 
When task FATHER is activated, it waits while its task CHILD is activated 
and a task designated %TASK 3 is created. CHILD executes one entry call 
on line 38, and then deadlocks because the entry is never accepted (see 
Section 16.7.1). 

Because time slicing is disabled and there are no higher priority tanka to.be 
run, FATHER will continue to execute past its activation until it is blocked 
the ACCEPT statement at line 47. 

Q A single task, MOTHER, is defined, and a task designated %TASK 4 is 
created. The pragma PRIORITY gives MOTHER a priority of 6. 

0 The task MOTHER begins its activation and executes line 91. After 

MOTHER is activated, the main program (%TASK 1) is eligible to resume i s 
execution. Because %TASK 1 has the default priority 7, which is higher than 
MOTHER’S priority, the main program resumes execution. 

0 This is the first rendezvous the main program makes with task FATHER. 
After the rendezvous FATHER will suspend at the SELECT with 
TERMINATE statement at line 58. 

0 At the third rendezvous with FATHER, FATHER raises the exception SOME. 
ERROR on line 67. The handler on line 72 catches the exception a or s 
the suspended CHILD task, and then reraises the exception; FATHER then 
terminates. 

0 A loop with a delay statement ensures that when control reaches line 122, 
FATHER has executed far enough to be terminated. 

® This entry call ensures that MOTHER does not wait forever for its rendezvous 
on line 93. MOTHER executes the accept statement (which involves no other 
statements), the rendezvous is completed, and MOTHER is immediately 
switched off the processor at line 94 because its pnonty is only b. 

0 After its rendezvous with MOTHER, the main program (%TASK 1) executes 
lines 127 through 129. At line 129, the mam program must wait for all its 
dependent tasks to terminate. When the main program reaches line 129, the 
only nonterminated task is MOTHER (MOTHER cannot terminate until the 
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null statement at line 97 has been executed) MnTTTPR ^ n 
esumes with the command line interpreter. 

16.3 Specifying Tasks in Debugger Commands 

A task is an entity that executes in parallel with other tasks A task i« 
«Tis£ a s et niqUe *■* ® (86e ^ 16 3 - 3) - * «««^ stack, and a 

context for mlnlpdating tasks's'e'e Sectional ™ We ‘ aSk determine the 
Wien specifying tasks in debugger commands, you can use any of the following 

to SettionTs^ToTaT deC ‘ ared “ * he Pr0gram <for exam P le . FATHE K 

S^rtton 16 5 2 d!i >. »Tf e express, °" yields a task value, 
section 16.3.2 describes Ada language expressions for tasks. 

• A task ID (for example, %TASK 2). See Section 16.3.3. 

A task built-in symbol (for example, %ACTIVE_TASK). See Section 16.3.4. 

16.3.1 Definition of Active Task and Visible Task 

The active task is the task that runs when a STEP, GO, CALL or EXIT 
a debugging session, use the SET TASK/ACTIVE command. d g 


Note 


The SET TASK/ACTIVE command does not work for DECthreads 
AJnh ° penV ^ S AJpha and VAX systems) or for Ada on OpenVMS 
Alpha systems, the tasking for which is implemented via DECthreads 

D n ECthre 0 ad S 7 TASK/ACTIVE ’ use the SET TASK/VISIBLE command on 

DaSwfh^r 17 ype acti0ns - 0r ’ t0 gain Contro110 ste P through a 
particular thread, use a strategic placement of breakpoints 


The following command makes the task named CHILD the active task: 

DBG> SET TASK/ACTIVE CHILD 

that th e debugger use' whenh^'ufs^tj^ster ralues! loutinl Zte* 

DBG> EXAMINE KEEP COUNT 

SETTASIWISTmV aSk ^ ^ task ’ T ° change the visible task, use the 

- to “ at -— 

You can specify the active and visible tasks in debugger commands bv usine 
%ACTIVE - TAS K » d %VISIBLE_TASK, respectfveTy Ze 
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16.3 Specifying Tasks in Debugger Commands 


See Section 16.5 for more information about using the SET TASK command to 
modify task characteristics. 


16.3.2 


Ada Tasking Syntax 

You declare a task either by declaring a single 
task type. For example: 


task or by declaring an object of a 


— TASK TYPE declaration, 
task type FATHER_TYPE is 


end FATHER_TYPE; 

task body FATHER_TYPE is 

end FATHER_TYPE; 

— A single task. 

task MOTHER is 

end MOTHER; 

task body MOTHER is 


end MOTHER; 

A task object is a data item that contains a task value A task ob j ect ^ s c ^ ated 
when the program elaborates a single task or task object, when you dec 
I record or a^ay containing a task component, or when a task allocator xs 

evaluated. For example: 

— Task object declaration. 


FATHER : FATHER_TYPE; 

— Task object (T) as a component of a record. 

type SOME_RECORD_TYPE is 

record 

A, B: INTEGER; 

T : FATHER_TYPE; 

end record; 

HAS_TASK : SOME_RECORD_TYPE; 

_ Task object (POINTERl) via allocator. 


type A is access FATHER_TYPE; 
POINTERl : A := new FATHER_TYPE; 


A task object is comparable to any other object. You refer to a task object 
bugger commands either by name or by path name. For example: 


in 


dbg> examine father 

DBG> examine father_type$task_body.child 

When a task object is elaborated, a task is created by the DEC Ada ^m-^® 
library, and the task object is assigned its task value. As wtbo 
the value of a task object is undefined before the object is initialized, and 
results of using an uninitialized value are unpredictable. 

The task body of a task type or single task is implemented in DEC Ada as a 
procedure This procedure is called by the DEC Ada run-time hbrary when a task 
of that type is activated. A task body is treated by the debugger as a normal Ada 
procedure, except that it has a specially constructed name. 
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16.3 Specifying Tasks in Debugger Commands 

to L b S i ^ef Ug8er C ° mmand ' me ‘ he f ° ll0wine *■““ “> ^ 

task-type-identifier$TASKJBODY 

Use the following syntax to refer to single tasks: 

task-identifiei$TASKJBODY 

For example: 

DBG> SET BREAK FATHER_TYPE$TASK BODY 

on these attributes^ Yq 66 ^ ^ ^ documentation for moreTnfomatteT 
CHILD'CALLART F S 0t 6nter commands such as EVALUATE 
oft^tl ^ALLABLE However, you can get the information provided by each 

informatfoL ai seS te.4 ^ ^ TASK F ° r 


16.3.3 Task ID 


A task ID has the following syntax, where n is a positive decimal integer 
%TASK n 

task < ^ect^^^^exampl^(Ada^path-name <) s^itex): 

DBG> EVALUATE FATHER 
%TASK 2 

DBG> EXAMINE FATHER 
TASK_EXAMPLE.FATHER: %TASK 2 

use^ ES™S™Sr ge d0eS J ” 0t T' buM - in ‘ askin ^ “*«•. leu must 

use tne EXAMINE/TASK command to obtain the task ID of a task. 

Note that the EXAMINEyTASK«EXADECIMAL command, when applied to a 
task object, yields the hexadecimal task value. The task value is th^ address of 
the task (or thread) control block of that task. For example (Ada example) 

DBG> EXAMINE/HEXADECIMAL FATHER 
TASK_EXAMPLE.FATHER: 0015AD00 
DBG> 

be h en S aSed A to^ L enaWeS y ° U t0 identify the task IDs tha t have 

been assigned to all currently existing tasks. Some of these existing tasks mav 

not be immediately familiar to you for the following reasons: Y 

DECthreadf p iSPk J indudeS taSkS Created by su bsystems like 

DECthreads Remote Procedure Call services, and the C Run-Time Library 

not just the tasks associated with your application. 

A SHOW TASK/ALL display includes task ID assignments that depend on 
The r samI a f tin te SyStem ’ ^ tasking service > and the generating subsystem 

sei^icerJafneTidenff^’ T °° dif f erent s y stems or ad Justed for different 
exception is %TASK T taaks with the same decimal integer. The only 

executes the main program SyStemS aSSign t0 the task that 
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16.4 Displaying Information About Tasks 


IU J ■■ II !■ W. -- 

To display information about one or more tasks of your program, use the SHOW 
TASK command. 

tVia QT-fOW TASK command displays information about existing (nonterminated) 
“Is By defe ^ r”mmand P dis y plays one line of information about the rouble 

ti9.sk 

Section 16.4.1 and Section 16.4.2 describe the information displayed by a SHOW 
TASK command for DECthreads and Ada tasks, respectively. 


16.4.1 Displaying Information About DECthreads Tasks 

The command SHOW TASK displays information about all of the tasks of the 
program that currently exist (see Example 16-3). 


Example 16-3 Sample SHOW TASK/ALL Display for DECthreads Tasks 


O 

task id 
%TASK 
%TASK 
ITASK 
%TASK 
* ITASK 
%TASK 
%TASK 
ITASK 
%TASK 
DBG> 


0 0 

© © 

state hold 

pri substate 

1 SUSP 

12 Condition Wait 

2 SUSP 

12 Mutex Wait 

3 SUSP 

12 Delay 

4 SUSP 

12 Mutex Wait 

5 RUN 

12 

6 READY 

12 

7 SUSP 

12 Mutex Wait 

8 READY 

12 

9 TERM 

12 Term, by alert 


© 

thread_object 
Initial thread 

T EXAMP\main\threads[0].fieldl 
T _ EXAMP\main\threads[1].fieldl 
T~EXAMP\main\threads[2].fieldl 
T~EXAMP\main\threads[3].fieldl 
T~EXAMP\main\threads[4].fieldl 
T - EXAMP\main\threads[5].fieldl 
T - EXAMP\main\threads[6].fieldl 
T~"EXAMP\main\threads[7].fieldl 


Key to Example 16-3: 

O The task ID (see Section 16.3.3). The active task is marked with an asterisk 
(*) in the leftmost column. 

© The current state of the task (see Table 16-3). The task in the RUN 

(RUNNING) state is the active task. Table 16-3 lists the state transitions 

possible during program execution. 

O Whether the task has been put on hold with a SET TASK/HOLD command as 
explained in Section 16.5.1. 


© The task priority. 

© The current substate of the task. The substate helps indicate the possible 
cause of a task’s state. See Table 16-4. 

© A debugger path name for the task (thread) object or the address of the task 
object if the debugger cannot symbolize the task object. 
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Table 16-3 Generic Task States 


Task State Description 

RUNNING 

mnnin ? 0n the P r ^essor. This is the active task. A 

2 TERM?NATED C stet“ 3 t0 READY > SUSPE NDED, 

READY 

?!£££¥££ 6X !u Ute Waiting for the Processor to be made 

RUNNING state " ““ make 3 transition °*ly to the 

SUSPENDED 

Task is suspended, that is, waiting for an event rather than for the 

Zl blht M fthe Pr ° C j S j° r ' For exam P le > When a task is created, it 
remains m the suspended state until it is activated. A task in this 

state Can make 3 transitlon onl y to the READY or TERMINATED 

TERMINATED 

InoLer t s e tate inated ' A “ tWs State Cannot make a transition to 

Table 16-4 DECthreads Task Substates 

Task Substate 

Description 

Condition Wait 

Delay 

Mutex Wait 

Not yet started 
Term, by alert 
Term, by exc 

Timed Cond Wait 

Task is waiting on a DECthreads condition variable. 

Task is waiting at a call to a DECthreads delay. 

Task is waiting on a DECthreads mutex. 

Task has not yet executed its start routine. 

Task has been terminated by an alert operation. 

Task has been terminated by an exception. 

Task is waiting on a timed DECthreads condition variable 


The SHOW TASK/FULL command provides detailed information 
task selected for display. Example 16-4 shows the output of this 
sample DECthreads task. 


about each 
command for 


a 


Example 16-4 Sample SHOW TASK/FULL Display for a DECthreads Task 


O task id state hold pri substate 
%TASK 4 SUSP 12 Delay 

® Alert is pending 

Alerts are deferred 


thread_object 

T_EXAMP\main\threads[1].fieldl 


0 

O 

© 


0 


Next pc: 

Start routine: 


Stack storage: 
Bytes in use: 
Bytes available: 
Reserved Bytes: 
Guard Bytes: 

Thread control b 
Size: 


SHARE$CMA$RTL+46136 
T_EXAMP\thread action 
throughput 


1288 

40185 

10752 

4095 

© Base: 

SP: 

Top: 

00334C00 

003346F8 

00329A00 

k: 

293 

Address 

: 00311B78 


(continued on next page) 
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16 4 2 Displaying Task Information About Ada Tasks 

The SHOW TASK/ALL command displays information about all of the tasks 
rffte program that currently exist^namely, taste that have been created and 
whose master has not yet terminated (see Example 16 6). 

Example 16-6 Sample SHOW TASK/ALL Display for Ada Tasks 




Alpha 


O © © © 

task id pri hold state 


7 

7 

7 

6 


0 

substate 

RUN 

HOLD SUSP Accept 

SUSP Entry call 
READY 


0 

task object 
S HARE $ADARTL+130428 
TASK EXAMPLE.MOTHER+4 

TASK"EXAMPLE.FATHER_TYPE$TASK_BODY.CHILD+4 
TASK _ EXAMPLE.MOTHER) 


* %TASK 1 

%TASK 2 

ITASK 4 

%TASK 3 

DBG> 

Key to Example 16-6: 

O The task ID (see Section 16.3.3). An asterisk indicates that the task is a 
visible task. 

© The task priority. Ada priorities range from 0 to 15. 

On VAX processors, a task is created with a defaultpnority of 7 unless 
another value is specified with the pragma PRIORITY. ♦ 

On Alpha processors, if time slicing is disabled, a task is created with a 
default prioity of 7; if time slicing is enabled, the » a tesk is created wi 
approximate midrange value (unless the pragma PRIORITY is 
specified). ♦ 

© Whether the task has been put on hold with a SET TASK/HOLD command 
as explained in Section 16.5.1. Placing a task on HOLD restricts the state 
transitions it can make after the program is subsequently allowed to execute. 

© The current state of the task (see Table 16-3). The task that is in the RUN 
(RUNNING) state is the active task. Table 16-3 lists the state transitions 

possible during program execution. 

© The current substate of the task. The substate helps indicate the possible 
cause of a task’s state. See Table 16—5. 

© A debugger path name for the task object or the address of the task object if 
the debugger cannot symbolize the task object. 
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Table 16-5 Ada Task Substates 
Task Substate 

Abnormal 
Accept 

Activating 
Activating tasks 
Completed [abn] 


Completed [exc] 


Completed 

Delay 

Dependents 
Dependents [exc] 

Entry call 
Invalid state 
I/O or AST 
Not yet activated 
Select or delay 

Select or terminate 
Select 

Shared resource 
Terminated [abn] 
Terminated [exc] 
Terminated 
Timed entry call 


?atement aiting ** ** statement that is not inside a select 

Task is elaborating its declarative part. 

Task is waiting for tasks it has created to finish activating. 

Task is completed due to an abort statement but is not yet 

fo^I nat !f' Pi A ? 3 ’ a com Pleted task is one that is waiting 
or dependent tasks at its end statement. After the dependent 
tasks are terminated, the state changes to terminated. 

SSin a ?T P T let ^ due t0 an unhandled exception 1 but is not yet 
terminated. In Ada, a completed task is one that is waiting for 

are'Sated 1 'the i nd vf tatement ' After the de Pendent tasks 

are terminated, the state changes to terminated. 

nnhpnHi«T Plete P’ ?° ab ° rt statem ent was issued and no 
unhandled exception 1 occurred. 

Task is waiting at a delay statement. 

Task is waiting for dependent tasks to terminate. 

Ivrtwi ting f ° r de P endent tasks to allow an unhandled 
exception to propagate. 

Task is waiting for its entry call to be accepted. 

There is an error in the DEC Ada run-time library. 

Task is waiting for I/O completion or some AST. 

Task is waiting to be activated by the task that created it. 

Task is waiting at a select statement with a delay 
alternative. 

Task is waiting at a select statement with a terminate alternative. 

Task is waiting at a select statement with no else, delay or 
terminate alternative. y ’ 

Task is waiting for an internal shared resource. 

Task was terminated by an abort statement. 

Task was terminated because of an unhandled exception. 1 

Task terminated normally. 

Task is waiting in a timed entry call. 


ktesafeas ? s/iSni's lhere 

Figure 16-1 shows a task stack. 

S H°W TASKiTOU. command provides detailed information about each 
^mp“ P ^ EXamP ‘ e Sh ° WS ‘ he "*"* ° f — for a 
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Example 16-7 Sample SHOW TASK/FULL Display for an Ada Task 


O task id 
* %TASK 2 


pri hold state substate 
7 RUN 


task object 
TASK EXAMPLE.MOTHER+4 


Waiting entry callers: 
Waiters for entry BOGUS: 
%TASK 4, type: CHILD 


© 

© 

© 

DBG> 


Task type: 
Created at PC: 


FATHER_TYPE 
TASK EXAMPLE 


Parent task: %TASK 1 

Start PC: TASK_EXAMPLE 

Task control block: 

Task value: 490816 

Entries: 3 

Size: 1488 

Stack addresses: 

Top address: 001EB600 
Base address: 001F2DFC 


.%LINE 14+22 

.FATHER_TYPE$TASK_BODY 

© Stack storage (bytes) 
RESERVED_BYTES: 
TOP_GUARD_SIZE: 
STORAGE_SIZE: 

Bytes in use: 

© Total storage: 


10640 

5120 

30720 

456 

47968 




Alpha 


Key to Example 16-7: 

O Identifying information about the task. 

© Rendezvous information. If the task is a caller task, it lists the entries for 
which it is queued. If the task is to be called, it gives information about the 
kind of rendezvous that will take place and lists the callers that are current y 
queued for any of the task s entries. 

© Task context information. 

© Task control block information. The task value is the address, in decimal 
notation, of the task control block. 

© Stack storage information: 

• RESERVED_BYTES gives the storage allocated by the Ada run-time 
library for handling stack overflow. 

• TOP_GUARD_SIZE gives the storage allocated for guard pages, which 
provide protection against storage overflow during task execution. 

On VAX processors, you can specify the number of J^ es be aS 

guard pages with the DEC Ada pragmas TASK_STORAGE and MA _ 
STORAGE; the number shown by the debugger is the number o ytes 
allocated (the pragma value is rounded up to an integral number of pages, 
as necessary). For more information about these pragmas and the top 
guard storage area, see the DEC Ada documentation. ♦ 

On Alpha processors, you can specify the number of bytes to be allocated 
as guard pages with the DEC Ada pragmas TASK_STORAGE; the number 
shown by the debugger is the number of bytes allocated (the pragma value 
is rounded up to an integral number of pages, as necessary). For m 
information about these pragmas and the top guard storage area, see 
DEC Ada documentation. ♦ 

• STORAGE_SIZE gives the storage allocated for the task activation. 


16-22 







Alpha 


1c , n . , Debugging Tasking Programs 
16.4 Displaying Information About Tasks 

^STORArF^P nUmb6r ° f byt6S t0 bG all0Cated ™ tb the 

STORAf^ L ^presentation clause or in the Ada pragma MAIN 

alb^dfthP v T 1 S°JT by the debu ^ er is the n ^ber of bytes" 

r aCtiVati ° n <W ° rkin8) ^ area - 

?STORArp if «r^ e ” Umber ° f byt6S ‘° •* aUocated with the 
I MORAGE SEE representation clause; the number shown by the 

debugger is the number of bytes allocated (the value specified is 

rounded up to an integral number of pages, as necessaiy). For more 

information about this representation clause and pragma and about the 

task activation (working) storage area, see the DEC Ada documentation. 

Bytes in use:" gives the number of bytes of stack currently allocated. 

© Stack addresses of the task stack. 

0 t T £ e „™K St0, ? ge “ Sed the task ' Adds to S<»‘her ‘he task control block size 
the number of reserved bytes, the top guard size, and the storage size 

The SHOW TASK/STATISTICS command reports some statistics about all 

7c e 16-8 shows the 0utput of the SH0W task 

s,sta Tlk!I™ command for a sample Ada tasking program on a VAX 
system. This information enables you to measure the performance of your 

P™f am - larger tbe . number of total schedulings (also known as context 
switches), the more tasking overhead there is. 

Example 18-8 SjmpteaHW TASK/STATISTICS/FULL Display lor Ada Tasks 

task statistics 
Entry calls 
Tasks activated 
ASTs delivered 
Total schedulings 

Due to readying a higher priority task = 1 
Due to task activations - 3 

Due to suspended entry calls = 4 

Due to suspended accepts = 1 

Due to suspended selects = 2 

Due to waiting for a DELAY = 0 

Due to scope exit awaiting dependents = 0 
Due to exception awaiting dependents = 0 
Due to waiting for I/O to complete = 0 
Due to delivery of an AST = 4 

Due to task terminations = q 

nD „ ^ ° ue t0 shared resource lock contention = 0 
DBG> <endsection> 


= 4 

Accepts = 1 

Selects 

= 3 

Tasks terminated 

= 0 

= 4 

Hibernations 

= 0 


16.5 Changing Task Characteristics 

use^h^SET ta ® 1 l® character j stics ° r the tasking environment while debugging, 
use the SET TASK command as shown in the following table: 
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4^ 


Command 

SET TASK/ACTIVE 

SET TASK/VISIBLE 
SET TASK/ABORT 


SET TASK/PRIORITY 
SET TASK/RESTORE 
SET TASK/[NO]HOLD 

SET TASK/TIME_SLICE 


Makes a specified task the active task; not for DECthreads 
oJnOpenVMS Alpha or VAX) or Ada on OpenVMS Alpha (see 
Section 16.3.1). 

Makes a specified task the visible task (see Section 16.3.1). 

Requests that a task be terminated at the next allowed 
opportunity. The exact effect depends on the current 
event facility (language dependent). For Ada tasks, this 
is equivalent to executing an abort statement. 

Sets a task’s priority. The exact effect depends on the current 
event facility (language dependent). 

Restores a task’s priority. The exact effect depends on the 
current event facility (language dependent). 

Controls task switching (task state transitions, see 
Section 16.5.1). 

Controls the time slice value or disable time slicing (see 
Section 16.5.2); supported for VAX Ada only, and not with 
DECthreads. ♦ 


For more information, see the SET TASK command description. 

16.5.1 Putting Tasks on Hold to Control Task Switching 

Task switching might be confusing when you are debugging a program. Placing a 
task on hold with the SET TASK/HOLD command restricts the state transitions 
the task can make once the program is subsequently allowed to execute. 

A task placed on hold can enter any state except the RUNNING st ^ te ' JJ' 
necessary, you can force it into the RUNNING state by using the SET TASK 

/ACTIVE command. 

The SET TASK/HOLD/ALL command freezes the state of all tasks_except the 
active task. You can use this command in combination with the SET 1 
/ACTIVE command, to observe the behavior of one or more specified tasks 
isolation by executing the active task with the STEP or GO command, and then 
switching execution to another task with the SET TASK/ACTIVE command. For 

example: 

DBG> SET TASK/HOLD/ALL 
DBG> SET TASK/ACTIVE %TASK 1 
DBG> GO 


DBG> SET TASK/ACTIVE %TASK 3 
DBG> STEP 


When you no longer want to hold a task, use the SET TASK/NOHOLD command. 
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16 ^.2 Debugging Programs That Use Time Slicing (VAX Ada Only) 

rwssisrsassss as ss?-> 

XgSZSr** S t ffl T ‘ aSk SWitches ' but to8ks of thfsamf 

priority also take turns executing for a specified neriod of timo o i- • 

causes tasks to execute more 

time SliCing mieh ‘ “* be re “ one run the 

The SET 1 TASK/TIME_SLICE=t command (supported for VAX Ada only) enables 
SLICE-00? y & n ©w time slice or disable time slicing (with SET TASK/TIME 
SLICE-0.0) Thus, you can tune the execution of your tasking programs or " 
diagnose problems that depend on the order in which tasks exfcute 


Note 


The SET TASK/TIME_SLICE command is supported for VAX Ada onlv 
and not for VAX Ada with DECthreads. If yofuse the cormnand ini’ 
unsupported context, the debugger issues the following error message: 

%DEBUG-E-NOTIMSLI, time slice modification not supported by this event facility 

Note that there is an interaction between time slicing and the debugger 
watchpoint implementation. When you set watchpoints, the debugger might 
automatically increase the value of the time-slice interval to 10.0 feconds 
Slowing the time-slice rate prevents some problems. ♦ 

16.6 Controlling and Monitoring Execution 

The following sections explain how to do the following functions: 

fndsTonr' 160 an<1 taSk ' independ6nt event P°ints (breakpoints, tracepoints, 

• Set breakpoints and tracepoints on DECthreads-specific task locations. 

Set breakpoints and tracepoints on Ada-specific task locations. 

* commands^ 6VentS ^ SET BREAK/EVENT or SET TRACE/EVENT 

16 . 6.1 Setting Task-Specific and Task-Independent Debugger Eventpoints 

^ an 6Vent that y ° U Can USe t0 return contro1 t0 th e debugger 
are ete^nJr S ’ Watchp ° ints ’ and the eompletion of STEP commands' 

A task-independent eventpoint can be triggered by the execution of any task 
in a program, regardless of which task is active when the eventpoint is set Task 
independent eventpoints are generally specified by an address expression such as 

following er ° r 3 I | ame f A11 . watch POints are task-independent eventpoints. The 
owing are examples of setting task-independent eventpoints: 

DBG> SET BREAK COUNTER 

DBG> SET BREAK/N0S00RCE %LINE 55, CHILD$TASK BODY 
DBG> SET WATCH/AFTER=3 KEEP_C00NT 
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A task-specific eventpoint can be set only for the task that is active when 
the command is entered. A task-specific eventpoint is triggered only when t 
same°task is active. For example, the STEP/LINE command 
eventpoint: other tasks might execute the same source line and not trigge 

event. 

If you use the SET BREAK, SET TRACE, or STEP commands with the following 
qualifiers, the resulting eventpoints are task specific: 

/BRANCH 

/CALL 

/INSTRUCTION 

/LINE 

/RETURN 

/VECTORJNSTRUCTION (VAX only) 

Anv other eventpoints that you set with those commands and anyeventpomts^^ 
that you set with the SET WATCH command are task independent. The following 
are examples of setting task-specific eventpoints: 

DBG> SET tScE/INSTRUCTION/SILENT DO (EXAMINE KEEP_COUNT) 

DBG> STEP/CALL/NOSOURCE 

You can conditionalize eventpoints that are normally task-independent to make 
them task specific. For example: 

DBG> SET BREAK %LINE 11 WHEN (%ACTIVE_TASK=FATHER) 

16.6.2 Setting Breakpoints on DECthreads Tasking Constructs 

You can set a breakpoint on a thread start routine_ The breakpoint will trigger 
just before the start routine begins execution. In Example 16-1, this type at 
breakpoint is set as follows: 

DBG> SET BREAK worker_routine 

Unlike Ada tasks, you cannot specify the body of a DECthreads task by name but 
the start routine is similar. 

Specifying a WHEN clause with the SET BREAK command ensures that you 
catch the point at which a particular thread begins execution. For examp e. 

DBG> SET BREAK worker_routine - 
_DBG> WHEN (%CALLER_TASK = %TASK 4) 

In Example 16-1, this conditional breakpoint will trigger when the second worker 
thread begins executing its start routine. 

Other useful places to set breakpoints are just prior to and immediately after 
condition waits, joins, and locking of mutexes. You can set such breakpoints by 
specifying either a line number or the routine name. 

16.6.3 Setting Breakpoints on Ada Task Bodies, Entry Calls, and Accept 
Statements 

You can set a breakpoint on a task body by using one of the following syntaxes to 
refer to the task body (see Section 16.3.2): 

task-type-identifier$ TASK_BODY 
task-identifier$TASKJBODY 
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CHILDThfs hr 6 i 0ll0W ! ng ?° mmand sets a breakpoint on the body of task 
, , D ;. Thls breakpoint is triggered just before the elaboration of the task’s 
declarative part (also called the task’s activation). 

DBG> SET BREAK CHILD$TASK_BODY 

K ta 0 mJaSn«TlT ^ ‘“'l"''’ 88 ° f the flrst the task 

this rZ u meaningful to set a breakpoint on an instruction, and hence on 

a SET BREAT£ WeVer ' ^ n0t 03016 the task ob J ect (for example, CHILD) in 

name designates the ^ 

nhZt + * ‘ J t as 14 1S erroneous to set a breakpoint on an integer 

object, it is erroneous to set a breakpoint on a task object. g 

You can monitor the execution of communicating tasks by setting breaknnints nr 
tracepoints on entry calls and accept statements g breakpoints or 


Note 


entwrSl tlT CaUS T* the Same 3S sub Program calls because task 

STEP comm ! 6 Ht eUe<1 and n0t eX6CUte right away ’ If you use the 
IVT command to move execution into a task entry call, the results 

might not be what you expect. 


want tn lfT al r t in Snd ar ° Und an accept stat ement where you might 
nropi-am * 3 breakp ° m4 °J tr acepoint. For example, consider the following 

RENDEZVOUS 11 ’ ^ ^ ^ statements for the same entry, 


10 

11 

12 

13 

14 

15 

16 

17 

18 

19 

20 
21 
22 


task body TW0_ACCEPTS is 
begin 

for I in 1..2 loop 
select 

accept RENDEZVOUS do 

PUT_LINE("This is the first accept statement"); 
end RENDEZVOUS; 
or 

terminate; 
end select; 
end loop; 

accept RENDEZVOUS do 

PUT_LINE("This is the second accept statement")* 
end RENDEZVOUS; 
end TWO ACCEPTS; 


You can set a breakpoint or tracepoint in the following places in this example: 

At the start of an accept statement (line 12 or 19). By setting a breakpoint 

Z :m nt T’ r Can moni tor when execution reaches the start of the 
accept statement where the accepting task might become suspended before a 
rendezvous actually occurs. apeuuea oeiore a 

13 or20) ai l° f ii e b0dy , (seqaence of statements) of an accept statement (line 
a reniW \ f breakpoint or tracepoint here, you can monitor when 
execution ^ Started ~ that is ’ when the acce Pt statement actually begins 

weno^hlr aCCGPt Statement (line 14 or 2D- By setting a breakpoint or 
tracepoint here, you can monitor when the rendezvous has completed and 
execution is about to switch back to the caller task. 
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To set a breakpoint or tracepoint in and around an accept statement, you can 
the associated line number. For example, the following command seta a 
breakpoint on the start and also on the body of the first a«ept statement in the 
preceding example: 

DBG> SET BREAK %LINE 12, %LINE 13 

To set a breakpoint or a tracepoint on an accept statement body you can also use 
Se^ name (specifying its expanded name to identify the task body where the 

entry is declared). For example: 

DBG> SET BREAK TWO_ACCEPTS$TASK_BODY.RENDEZVOUS 

If there is more than one accept statement for an entry, the debugger treats tiie 
entry as an overloaded name. The debugger issues a message indicating that 
theTySbol is overloaded, and you must use the SHOW SYMBOL command to 
identify the overloaded names that have been assigned by the debugger, 
example: 

DBG> SHOW SYMBOL RENDEZVOUS 

overloaded symbol TEST.TWO ACCEPTS$TASK_BODY.RENDEZVOUS 

overloaded instance TEST7TW0_ACCEPTS$TASK_B0DY.RENDEZVOUS 1 
overloaded instance TEST.TW0_ACCEPTS$TASK_B0DY.RENDEZV0US_2 

Overloaded names have an integer suffix preceded by two underscores For 
more information on overloaded names, see the debuggers online help (type 
HELP Language ADA). 

To determine which of these overloaded names is associated with a particular 
accept statement, use the EXAMINE/SOURCE command. For example. 

DBG> examine/source two_accepts$task_body.rendezvous_i 
module TEST ACCEPTS 

12* accept RENDEZVOUS do 

DBG> examine/source two_accepts$task_body.rendezvous_ 2 
module TEST ACCEPTS 

]_ 9 ; accept RENDEZVOUS do 

In the following example, when the breakpoint triggers, the caller^task is 
evaluated (see Section 16.3.4 for information about the symbol %CALLER_TASK). 

DBG> SET BREAK TWO_ACCEPTS$TASK_BODY.RENDEZV0US_2 - 
DBG> DO (EVALUATE %CALLER_TASK) 

The following breakpoint triggers only when the caller task is %TASK 2: 


DBG> SET BREAK TW0_ACCEPTS$TASK_B0DY.RENDEZV0US_2 - 

DBG> WHEN (%CALLER_TASK = %TASK 2) 


If the calling task has more than one entry call to the same accept statement you 
can use the SHOW TASK/CALLS command to identify the source line where 
fintrv call was issued. For example: 


DBG> set BREAK TW0_ACCEPTS$TASK_B0DY.RENDEZV0US_2 

DBG> DO (SHOW TASK/CALLS %CALLER_TASK) 
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16.6.4 


Monitoring Task Events 

The SET BREAK/EVENT and SET TRACF/FVE’wt ™ j 

seltracepotts Ihtt F* e ™ tS ' 

CHILD or %TASK 2 makes a transrtioTto^25? s ta te ‘ ^ “ 

DBG> SET TRACE/EVENT=RUN CHILD,%TASK 2 

:5&r of “—• -— 

- <P«* With the 

tesks. 16-6 liStS the generiC Ianguage - ind ependent events common to all 

Table 16-7 lists the events specific to DECthreads tasks. 

Table 16-8 lists the events specific to Ada tasks. 



RUN 

PREEMPTED 

ACTIVATING 

SUSPENDED 


Triggers when a task is about to run. 

Triggers when a task is being preempted from the RUN state and 
its state changes to READY. (See Table 16-3.) 

Triggers when a task is about to begin its execution. 

Triggers when a task is about to be suspended. 


Table 16-7 DECthreads-Specific Events 

Event Name 


Description 


HANDLED 

TERMINATED 

EXCEPTION_TERMINATED 

FORCED_TERM 


^ igge r® when an exception is about to be handled in 

some TRY block. 

Triggers when a task is terminating (including by alert 
or exception). J 

Triggers when a task is terminating because of an 
exception. 

Triggers when a task is terminating due to an alert 
operation. 


Table 16-8 Ada-Specific Events 


Event Name 


Description 


HANDLED 


HANDLED_OTHERS 


Triggers when an exception is about to be handled 

in some Ada exception handler, including an others 
handler. 

Triggers only when an exception is about to be handled 
in an others Ada exception handler. 

(continued on next page) 
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Execution 



TERMINATED 
EXCEPTION_TERMINATED 
ABORT_TERMINATED 


Triggers when an exception causes a task to wait or 
dependent tasks in some scope (includes unhandled 
exceptions, 1 which, in turn, include special exceptions 
internal to the DEC Ada run-time library, for more 
information, see the DEC Ada documentation). Often 
immediately precedes a deadlock. 

Triggers when a task is terminating, whether 
normally, by an abort statement, or by an exception. 

Triggers when a task is terminating due to an 
unhandled exception. 1 

Triggers when a task is terminating due to an abort 
statement. 

scope. _____ 

In the previous tables, the exception-related events are included for completeness. 
Only the task events are discussed in the foilowing pam^aphs^ For mwe 
information about the exception events, see the debuggers online help (type 
HELP Language ADA). 

You can abbreviate an event-name keyword to the minimum number of characters 
that make it unique. 

The event-name keywords that you can specify with the SET BREAK/EVENT 
or SET TRACE/EVENT command depend on the current event facility, whic 
is eifher THREADS or ADA in the case of task events. The appropriate event 
facilitv is set automatically when the program is brought under debugger contro . 
The SHOW EVENT FACILITY command identifies the facility that is cmrently 
J et and lists the vahd event name keywords for that facility (including those for 

the generic events). 

Several examples follow showing the use of the /EVENT qualifier: 

DBG> SET BREAK/EVENT=PREEMPTED 

DBG> GO 

break on THREADS event PREEMPTED 

t 3 qV %task 4 is netting preempted by -sTASK J 


DBG> set break/event=suspended 
DBG> GO 

break on THREADS event SUSPENDED 

Task %TASK 1 is about to be suspended 


DBG> SET BREAK/EVENT=TERMINATED 

DBG> GO 

break on THREADS event TERMINATED 

Task %TASK 4 is terminating normally 
DBG> 
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a ~ ~ a —»«- *■» 

' event breakpomte arc predeted for 

EXCEPTIONJTERMINATED and DEPENDENTS_EXCEPTION event 
routines!^ Predefined for Ada P ro ^ ams or programs that call Ada 

Ada examples of the predefined and other types of event breakpoints follow. 

Example of EXCEPTION_TERMINATED Event 

When the EXCEPTION.TERMINATED event is triggered, it usually indicates an 
unanticipated program error. For example: Y mdlcates an 

break on ADA event EXCEPTION TERMINATED 

Task -sTASK 2 is terminating because of an exception 

-ADA-F’EXCEPnof C F Pti °, n ' WaS at 3 " r3ise; " or "accept" 

ADA F EXCEPTION, Exception SOME ERROR F 

dbg> ~ ADA_F ' EXCRAIPRI ' Exception raised prior to PC = 00000B61 

Example of DEPENDENTS_EXCEPTION Event (Ada) 

For Ada programs the DEPENDENTSJ5XCEPTI0N event often unexpectedly 
precedes a deadlock. For example: unexpectedly 

break on ADA event DEPENDENTS_EXCEPTION 

Ta 5 D A-F-EXCC0P Y ^ wait dependent tasks because of this exception: 

ADA F EXCCOP, Exception was copied at a "raise;" or "arrant-« 

-ADA-F-EXCEPTION, Exception SOME ERROR P 

dbg> -ADA_F ~ EXCRAIPRI ' Exception raised prior to PC = 00000B61 

Example of RENDEZVOUS_EXCEPTION Event (Ada) 

For Ada programs the RENDEZVOUS_EXCEPTION event enables you to see an 

loTt e L°to c * lt aVeS 3 rendezvous (before exception information has been 
lost due to copying the exception into the calling task). For example: 

break on ADA event RENDEZVOUS_EXCEPTION 

EX onnn 1 m n 1S P ro P a 9 atini ? ou t of a rendezvous in task %TASK 2 
«ADA-F-CONSTRAINT_ERRO, CONSTRAINT_ERROR 

dbg> " ADA ” I_EXCRAIPRI ' Exception raised prior to PC = 00000BA6 

break P° ints (° r tracepoints) set with the /EVENT qualifier use the 
CANCEL BREAKEVEN (or CANCEL TRACE/EVENT) coZand 8^ the 
event qualifier and optional task expression in the CANCEL command exactly as 
you did with the SET command, excluding any WHEN or DO clauses. 

You might want to set event breakpoints and tracepoints in a debugger 
initialization file for your tasking programs. For example: 

SET BREAK/EVENT=ACTIVATING 

SET BREAK/EVENT=HANDLED DO (SHOW CALLS) 

SET BREAK/EVENT=ABORT_TERMINATED DO (SHOW CALLS) 

SET BREAK/EVENT=EXCEPTION TERM DO (SHOW CALLS) 

SET BREAK/EVENT=TERMINATED 
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16.7 Additional Task-Debugging Topics 

The following sections discuss additional topics related to task debugging: 

• Deadlock 

• Automatic stack checking 

• Using Ctrl/Y 

16.7.1 Debugging Programs with Deadlock Conditions 

A deadlock is an error condition in which each task in a group of tasks is 
Suspended a nd n0 task in the group can resume execution untd some o her task 
in the group executes. Deadlock is a typical error in tasking programs (in.much 
thesame way that infinite loops are typical errors in programs that use WHILE 

statements). 

A deadlock is easy to detect: it causes your program to appear to suspend, or 
hane in midexecution. When deadlock occurs in a program that is running unde 
debugger control, press Ctrl/C to interrupt the deadlock and display the debugger 

prompt. 

In general, the SHOW TASK/ALL command (see Section 16.4) or the SHOW 
TASK/STATE=SUSPENDED command is useful because ^hows which task 
are suspended in your program and why. The command SET TASK/VIbIBL*. 
%NEXT_TASK is particularly useful when debugging in screen mode. It enables 
you to cycle through all tasks and display the code that each task is executing, 
including the code in which execution is stopped. 

The SHOW TASK/FULL command gives detailed task state information, 
including information about rendezvous, entry calls, and entry index va ues. 

The SET BREAK/EVENT or SET TRACE/EVENT command (see Section 16 6.4) 
enables you to set breakpoints or tracepoints at or near lo cations that might ea 
to deadlock The SET TASK/PRIORITY and SET TASK/RESTORE commands 
enable you to see if a low-priority task that never runs is causing the deadlock. 

Table 16-9 lists a number of tasking deadlock conditions and suggests debugger 
commands that are useful in diagnosing the cause. 

Table 16-9 Ada Tasking Deadlock Conditions and Debugger Commands for 
Diagnosing Them 


Deadlock Condition 


Debugger Commands 


Self-calling deadlock (a task calls 
one of its own entries) 

Circular-calling deadlock (a task 
calls another task, which calls the 
first task) 

Dynamic-calling deadlock (a 
circular series of entry calls exists, 
and at least one of the calls is a 
timed or conditional entry call in a 
loop) 


SHOW TASK/ALL 

SHOW TASK/STATE=SUSPENDED 
SHOW TASK/FULL 

SHOW TASK/ALL 

SHOW TASK/STATE=SUSPENDED 

SHOW TASK/FULL 

SHOW TASK/ALL 

SHOW TASK/STATE=SUSPENDED 

SHOW TASK/FULL 


(continued on next page) 
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Table16 ~ 9(Cont - ) ,r;r*r condi,ions and Debu39w c °~ 

Deadlock Condition 


Exception-induced deadlock (an 
exception prevents a task from 
answering one of its entry calls, 
or the propagation of an exception 
must wait for dependent tasks) 

Deadlock due to incorrect run¬ 
time calculations for entry 
indexes, when conditions, and 
delay statements within select 
statements 

Deadlock due to entries being 
called in the wrong order 

Deadlock due to busy-waiting on 
a variable used as a flag that is to 
be set by a lower priority task, and 
the lower priority task never runs 
because a higher priority task is 
always ready to execute 


SHOW TASK/ALL 

SHOW task/state=suspended 

SHOW TASK/FULL 

SET BREAK/EVENT=DEPENDENTS EXCEPTION 

(for Ada programs) 

SHOW TASK/ALL 

SHOW TASK/STATE=SUSPENDED 

SHOW TASK/FULL 

EXAMINE 

SHOW TASK/ALL 

SHOW TASK/STATE=SUSPENDED 

SHOW TASK/FULL 

SHOW TASK/ALL 

SHOW TASK/STATE=SUSPENDED 

SHOW TASK/FULL 

SET TASK/PRIORITY 

SET TASK/RESTORE 


Automatic Stack Checking in the Debugger 

In tasking programs, an undetected stack overflow can occur in certain 
circumstances and can lead to unpredictable execution. (For more information 
on task stack overflow, see the DEC Ada or DECthreads documentation.) The 
ebugger automatically does the following stack checks to help you detect the 

dZi ° Verfl ° W Pr0MemS 8f the Stack P° illter is Abounds, the 

debugger displays an error message): 

A stack check is done for the active task after a STEP command executes or 

b /J P T TT S?| erS (SGe Section 1661 >- (This check is not done if you have 
used the /SILENT qualifier with the STEP or SET BREAKPOINT command.) 

TA S ct Ck CheCk j S d mu 6 f ° r each task whose state is displayed in a SHOW 

11 ^ S ; a u SH ? W TASK/ALL command automatically causes 

the stacks of all tasks to be checked. 

The following examples show the kinds of error messages displayed by the 

has U h r Whan a stack 'he* fails. A warning is issued when most of the stack 
has been used up, even if the stack has not yet overflowed. 

warning: %TASK 2 has used up over 901 of its stack 
SP. 0011194C Stack top at: 00111200 Remaining bytes: 1868 

error: %TASK 2 has overflowed its stack 
SP. 0010E93C Stack top at: 00111200 Remaining bytes: -10436 

error: %TASK 2 has underflowed its stack 
SP: 7FF363A4 Stack base at: 001189FC Stack top at: 00111200 

One of the unpredictable events that can happen after a stack overflows is that 
the stack can then underflow. For example, if a task stack overflows and the stack 

an ACC^O^ondT the w* ^ ° perating s y stem wiU attempt to signal 

area of t^e stack Jr' beCaUSe the top guard area is not a writable 

ACCWO ^ef;h s h° Per l Sy Cann0t Write the SignaI argument s for the 
VIO. When this happens, the operating system cuts back the stack: it causes 
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Debugging Tasking Programs 

16.7 Additional Task-Debugging Topics 

to force an image exit. 

Tf a time-slice AST or other AST occurs at this instant, execution can resume in a 
different task and for a while, the program may continue to execute, although no 
no“v (the task whose stack overflowed may use-and overwnte-the main 
nroeram stack). The debugger stack checks help you to detect this situation, 
vou'step into a task whose stack has been cut back by the operating system or 
[f you use the SHOW TASK/ALL command at that time, the debugger issues its 

stack underflow message. 

16 7 3 Using Ctrl/Y When Debugging Ada Tasks 

Pressing Ctrl/C is the recommended method of interrupting program execution 
or a debugger command during a debugging session. This returns control to the 
debugger; pressing Ctrl/Y returns control to DCL level. 

If you interrupt a task debugging session by pressing CtrVY, y ou mighthave 
some problems when you then start the debugger at DCL level with the DEBU 
command. In such cases, you should insert the following(two hnes 
code at the beginning of your main program to name the DEC Ada predefined 
package CONTROL_C_INTERCEPTION: 

with CONTROL C INTERCEPTION; 

pragma ELABORATE(CONTROL_C_INTERCEPTION); 

For information on this package, see the DEC Ada documentation. 
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Part III 

Debugger Command Dictionary 













detailed "*«“ — 
• Section 1 explains how to enter debugger commands. 

’ ^bugger’s DEC^ndo^^oth’tnterface^ *“ COmmand/mess ^ view of 

a workstation mnnTnTvWS^ ^ Whe “ y0U ^ USing the debu ^ er at 
Section 4 gives general information about debugger diagnostic messages. 
Jmids' 011 ^ 118 detailed referenCe information a bout the debugger 


1 Debugger Command Format 


You can enter debugger commands interactively at the keyboard or store them 

^d~ d procedure 40 be “ laL with 

This section gives the following information: 

• General format for debugger commands 

Rules for entering commands interactively at the keyboard 

• Rules for entering commands in debugger command procedures 

1.1 General Format 

AC m T nd String iS thG C ° mpIete s P ecifi cation of a debugger command 
Although you can continue a command on more than one line the term command 
string is used to define an entire command that is pasJiT^^r^ 

quahfiefr C ° mmand ^ C ° nSiStS ° f 3 VCrb 3nd ’ P ° ssibl * Parameters and 

The verb specifies the command to be executed. Some debugger command strings 
might consist of only a verb or a verb pair. For example: g 

DBG> GO 

DBG> SHOW IMAGE 

A parameter specifies what the verb acts on (for example, a file specification) 

A qualifier describes or modifies the action taken by the verb. Some command 

examp S leTcOUNT i e j ne ° r qualifiers ‘ In tha following 

examples, COUNT, I, J, and K, OUT2, and PROG4.COM are parameters (@is the 

execute procedure command); /SCROLL and /OUTPUT are qualifiers. H 

DBG> SET WATCH COUNT 
DBG> EXAMINE I,J,K 
DBG> SELECT/SCROLL/OUTPUT 0UT2 
DBG> 0PROG4.COM 

° r do *—■» a. 9 o ^ 

A WHEN clause consists of the keyword WHEN followed by a conditional 
expression (within parentheses) that evaluates to true or false in the current 
nguage. A DO clause consists of the keyword DO followed by one or more 
mmand strings (within parentheses) that are to be executed in the order that 
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they are listed. You must separate multiple command strings with semicolons (;). 
These points are illustrated in the next example. 

The following command string sets a breakpoint on routine SWAFThe breakpoint 

is triggered whenever the value of J equals 4 dunng execution. 

wSSta triggered, the debugger executes the two commands SHOW CALLS 

and EXAMINE I,K, in the order indicated. 

DBG> SET BREAK SWAP WHEN (J = 4) DO (SHOW CALLS; EXAMINE I,K) 

The debugger checks the syntax of thei commands m..i DO clause when it executes 
the DO clause. You can nest commands within DO clauses. 

1.2 Entering Commands at the Keyboard 

When entering a debugger command interactively at the keyboard you can 

commonly used commands (for example, EXAMINE, DEPOSIT, OO ca 

abbreviated to their first characters. Also, in some cases the debugger interp 
nonunique abbreviations correctly on the basis of context. 

Pressing the Return key terminates the current line, causing the debugger to 
process* To continue a long command string on another line, type a hyp 
? , before pressing Return. As a result, the debugger prompt is prefixed with a 
underscore character (_DBG>), indicating that the command string is still being 

accepted. 

You can enter more than one command string on one line by separating comman 
strings with semicolons (;). 

To enter a comment (explanatory text recorded in a debugger log file but 
otherwise ignored by the debugger), precede the comment text with a 
exclamation point (!). If the comment wraps to another line, start that 
with an exclamation point. 

The command line editing functions that are available at the DCL prompt ($) 

Ire also available at the debugger prompt (DBG>), including command [ recaU 
with the up arrow and down arrow keys. For example, pressing the left arrow 
Indright Low keys moves the cursor one character to the left and right 
respectively pressing Ctrl/H or Ctrl/E moves the cursor to the start or end of 
the line, respectively; pressing Ctrl/U deletes all the characters to the left of the 

cursor, and so on. 

To interrupt a command that is being processed by the debugger, press Ctrl/C. 
See the Ctrl/C command. 

1 3 Entering Commands in Command Procedures 

To maximize legibility, it is best not to abbreviate command keywords in a 
command procedure. Do not abbreviate command keywords to less than four 
significant characters (not counting the negation /NO . . . ), to avoid potentia 
conflicts in future releases. 

Start a debugger command line at the left margin. (Do not start a command line 
^a dollar S s g ign ($) as you do when writing a DCL command procedure.) 

The beeinning of a new line ends the previous command line (the end-of-file 
characSr also ends the previous command line). Th continue a command stnng 
on another line, type a hyphen (-) before starting the new me. 
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IZ7X r command string ° n ° ne iine by «nd 




-j. 

lnte“ dS DiSab ' ed ,h@ Debu 99 er s DECwindows Motif 


toterfal!e 0W Mf„vm S ^ d r We . d in , the deb ^’ s DECwindows Motif 
mode. 306 releVimt °" Iy to the comman d interface’s screen 


ATTACH 
CANCEL MODE 
CANCEL WINDOW 
DEFINE/KEY 
DELETE/KEY 
DISPLAY 

EXAMINE/SOURCE 
EXPAND 
EXTRACT 
HELP 1 
MOVE 
SAVE 
SCROLL 


SELECT 

(SET,SHOW) ABORT_KEY 
(SET,SHOW) KEY 
(SET,SHOW) MARGINS 
SET MODE [NOJKEYPAD 
SET MODE [NO]SCREEN 
SET MODE [NOjSCROLL 
SET OUTPUT [NOJTERMINAL 
(SET,SHOW) TERMINAL 
(SET,SHOW) WINDOW 
(SHOW,CANCEL) DISPLAY 
SHOW SELECT 
SPAWN 


hHelp on commands is available from the Help menu in a debugger window. 

The debugger issues an error message if you try to enter any of these disabled 

commands at the command prompt or when the debugger executes a command 
procedure containing any of these commands. command 

The MONITOR command works only with the DECwindows Motif interface 
(because the command uses the Monitor View). 


3 Commands Recognized Only on Workstations Running VWS 

_ • . ** 


The following commands are recognized only when you are using the debumrer at 
a workstation runmng VWS (not DECwindows Motif): g gg * 


SET MODE [NO]SEPARATE 
SET PROMPT/[NO]POP 


4 Debugger Diagnostic Messages 

The following example shows the elements of a debugger diagnostic message: 

%DEBUG-gNOSYMBOL, symbol 'X' is not in^the symbol table 

O The facility name (DEBUG). 

© The severity level (W, in this example). 
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0 The message identifier (NOSYMBOL, in this example). The message 
identifier is an abbreviation of the message text. 

O The message text. 

The identitor enables you to tod the explanation to- a ^gnosttc message from 
the debugger’s online help (and the action you need to take, if any). 

Tb get online help about a debugger message, use the following command format: 

HELP MESSAGES message-identifier 

The possible severity levels for diagnostic messages are as follows: 

S (success) 

I (informational) 

W (warning) 

E (error) 

F (fatal, or severe error) 

Success and informational messages inform you that the debugger has performed 
your request. 

Warning messages indicate that the debugger might have performed some, but 
not all, of your request and that you should verify the result. 

Frror messages indicate that the debugger could not perform your request, but 
that the state of the debugging session was not changed. The only exceptions ar 
tf 1message^identifier wfs DBGERR or INTERR. These identifiers signify an 
internal debugger error, and you should submit a Software Performance Report 
(SPR) in such cases. 

Fatal messages indicate that the debugger could not perform your request and 
that the debugging session is in an indeterminate state from w ic you canno 
recover reliably. Typically, the error ends the debugging session. 

5 Debugger Command Dictionary 

The Debugger Command Dictionary describes each debugger command in detail. 
Commandsare listed alphabetically. The following information is provided for 
each command: command description, format, parameters, qualifiers, and one or 
more examples. See the preface of this manual for documentation conventio . 
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@ (Execute Procedure) 



Format 


Parameters 


Executes a debugger command procedure. 


@file-spec [parameter!, ... ]] 


Description 


file-spec 

Specifies the command procedure to be executed. For any part of the f„ll fil 

“ta" n sET"k? debu8 f r f uses the file 

specification was not established"^’ SETOTaGNb* 

a“ S™ BUG C0M - - ^“a^, d tff^ 

parameter 

command procedures, see the DECLARE command. g P to 


debugger command procedure can contain any debugger commands includi™ 
another execute procedure (@) command. The debugger executes command f 
the command procedure until it reaches an FXTT nf otttt commands from 

the end of the command procedure At^ that S thS “““T* 0r reacheS 

Stre T i-okedthe command^procedure.^^commaifd'^trearn^ 0 

an be the terminal, an outer (containing) command procedure a DO ria, 0 • 
command such as SET BREAK, or a DO clause in a Lien display deSn “ 

fnte d r fte SETOimm Comn,and P™**"™ are not echoed. If you 

(Xtrr T h Td m= “ d ^ 

(the default output device is SYS$OUTPUT). ^ •puuir’ui 

DECLA^TOmman 0 ^ PaSSmg parameters to command procedures, see the 


Related commands: 

DECLARE 

(SET,SHOW) ATSIGN 
SET OUTPUT [NO]VERIFY 
SHOW OUTPUT 
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@ (Execute Procedure) 


Example 


DBG> SET ATSIGN USER:[JONES.DEBUG].DBG 

dbg> set output verify 


DBG> 0CHECKOUT 
%DEBUG-I-VERIFYICF, 
SET MODULE/ALL 
SET BREAK SUB1 


entering command procedure CHECKOUT 


break at routine PROG5XSUB2 
EXAMINE X 

PROG5\SUB2\X: 376 


%DEBUG-I-VERIFYICF, exiting command procedure MAIN 

DBG> , 

i , v oft ATSIGN command establishes that debugger command 
^—CdeSCmSESSNES.DEBUGl and have a ffletype 
nf DBG The ©CHECKOUT command executes the command procedure 
USEMJONES.DEBUG1CHECKOUT.DBG. The debugger echoes commands 
in the command because of the SET OUTPUT VERIFY command. 
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ACTIVATE BREAK 


Format 


Parameters 


Activates a breakpoint that you have previously set and then deactivated. 

ACTIVATE BREAK [address-expressionf, ... ]] 


Qualifiers 


address-expression 

Specifies a breakpoint to be activated. Do not use the asterisk (*) a 

/ACTIVATING 

TOlueMULTIPRoSs) 8 Art'' 8 !'" 8 c ' mf, « u, ' atKm '“ h ™ DBGJPROCESS has the 

a pomt established by a prevj,ms SET 

/ALL 

™EDEFINPn iVa t teS . a11 “ Ser ^ eftned breakpoints. When used with 

predefined breakpoints but no user-defined 
eakpoints. To activate all breakpoints, use /ALL/USER/PREDEFINED. 

/BRANCH 

command & breakp ° int estabIished b y a previous SET BREAK/BRANCH 

/CALL 

Activates a breakpoint established by a previous SET BREAK/CALL command. 

/EVENT=event-name 

Activates a breakpoint established by a previous SET BREAKZEVENT=euen« 
name command. Specify the event name (and address expression if any) exactly 
as specified with the SET BREAK/EVENT command. Y tly 

?HOW^SSS n "d“ d the a “ - »• 

/EXCEPTION 

command * breakp ° int estabIished b y a previous SET BREAK/EXCEPTION 

/INSTRUCTION 

Command * breakp ° int established b y a previous SET BREAK/INSTRUCTION 

/LINE 

nfw 68 3 breakpo “ t established by a previous SET BREAK/LINE command 
Do not specify an address expression with this qualifier. 


CD-9 




ACTIVATE BREAK 


Alpha 




SesTbreakpomt established by a previous SET BREAKiTERMINATING 
command. 

/UNALIGNED_DATA 

On Alnha Drocessors activates a breakpoint established by a previous SET 
BREAK/UNALIGNED J3ATA command, or reactivates a breakpoint previous y 
disabled by a DEACTIVATE /UNALIGNED.DATA command. ♦ 

/USER qualifier is the default unless you specify /PREDEFINED. 

/VECTORJNSTRUCTION 

On VAX processors, activates a breakpoint established by a previous SET BREAK 
/VECTORJNSTRUCTION command. ♦ 


Description 


User-defined breakpoints are activated when you set them vrith the SOT 
command Predefined breakpoints are activated by default. Use the ACllVAiE 
BREAK command to activate one or more breakpoints that you deactrvated with 

DEACTIVATE BREAK. 

Activating and deactivating breakpoints enables you to run andI rerun^ your 
nroeram with or without breakpoints without having to cancel and then reset 
them. By default, the RERUN command saves the current state of all breakpoin 

(activated or deactivated). 

You can activate and deactivate user-defined breakpoints or P re ^ fi £® d 
breakpoints or both. To check if a breakpoint is activated us ® S gil W BREAK 
BREAK command. For more information about breakpoints, 
and CANCEL BREAK commands. 

Related commands: 

CANCEL ALL 
RERUN 

(SET,SHOW,CANCEL,DEACTIVATE) BREAK 
(SET,SHOW) EVENT JACILITY 


Examples 


DBG> ACTIVATE BREAK MAIN\LOOP+10 

This command activates the user-defined breakpoint set at the address 
expression MAINXLOOP+IO. 
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ACTIVATE BREAK 


2. DBG> ACTIVATE BREAK/ALL 

This command activates all user-defined breakpoints. 

3. DBG> ACTIVATE BREAK/ALL/USER/PREDEFINED 

This command activates all breakpoints, both user-defined and predefined. 
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activate trace 



ACTIVATE TRACE 

Activates a tracepoint that you have previously set and then deactivated. 


Format 

ACTIVATE TRACE [address-expression[, .. ■ ]] 


Parameters 




Qualifiers 


£pTf™ multiprocess debugging configuration (when DBQ$PROCBSS has the 
value MULTIPROCESS). Activates a tracepoint established with a previous 
TRACE/ACTIVATING command. 

^default activates all user-defined tracepoints. When used with 

/PREDEFINED, it activates all predefined ^^gg^^DEFINED 116 
tracepoints. To activate all tracepoints, use /ALL/USER/PREDEJ? 1 

Activates^ a tracepoint established with a previous SET TRACE/BRANCH 
command. 

Activates a tracepoint established with a previous SET TRACE/CALL command. 

ActWate^a^racepoint established with a previous SET TRACE/EVENT=euen*- 
name command. Specify the event name (and address expression, if any) exa y 
as specified with the SET TRACE/EVENT command. 

To identify the current event facility and the associated event names, use the 
SHOW EVENT_FACILITY command. 

AcLVatel 1 a tracepoint established with a previous SET TRACE/EXCEPTION 
command. 

Activates^a'tracepoint established with a previous SET TRACE/INSTRUCTION 
command. 

Activates a tracepoint established with a previous SET TRACE/LINE command. 

Actuates'specified predefined tracepoint without affecting any user-defined 
tracepoints. When used with /ALL, activates all predefined tracepoints. 
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ACTIVATE TRACE 


/TERMINATING 

Command 8 traCeP ° int established with a previous SET TRACE/TERMINATING 


Description 


/USER 

Activates a specified user-defined tracepoint without affecting any predefined 

ST’l. .fl ™‘ h /ALL ' “ activates a11 user-defined tracepdnte The 
/USER qualifier is the default unless you specify /PREDEFINED. 

/VECTORJNSTRUCTION 

a SET 


Examples 


^mmand n ^rpX C r°^ tS act f Vated when set them with the SET TRACE 
TRACE mm ed tracepomts are activated by default. Use the ACTIVATE 

S^CTIWE^CE ° ne ° r ^ tracepoints that y° u deactivated with 
^l^ra^with'or i^theut*traTOpeints n wdthout^haWng to <^ce” an^theiTreset 

SaS rrS RUN — 4 a » — 

w both 1 2 ^Wl/"/ < ! eacUva .‘ e 'user-defined tracepoints or predefined tracepoints 
For mo' T ? k 5 3 tracepoint 1S activated, use the SHOW TRACE command 
T J ™ e information about tracepomts, see the SET TRACE and CANCEL 
1KACE commands. 


Related commands: 

CANCEL ALL 
RERUN 

(SET,SHOW) EVENTJFACILITY 

(SET,SHOW,CANCEL,DEACTIVATE) TRACE 


1. DBG> ACTIVATE TRACE MAIN\LOOP+10 

MAIN\LOOpllO CtiVateS tHe USer ' defined trace P 0 i n t at the location 


2. DBG> ACTIVATE TRACE/ALL 

This command activates all user-defined tracepoints. 
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ACTIVATE WATCH 


ACTIVATE WATCH 

Activates a watchpoint that you have previously set and then deactivated. 


Format 


ACTIVATE WATCH [address-expression[, ... ]] 


Parameters 


Qualifiers 


SpSaTatcSnt to be activated. With high-level languages, this is typically 
KSe of a variable. Do not use the asterisk (*) wildcard character Instead, 
use the /ALL qualifier. Do not specify an address expression with /ALL. 


/ALL 

Activates all watchpoints. 


Description 


Watchpoints are activated when you set them with the SET WATCH command. 
Use the ACTIVATE WATCH command to activate one or more watchpoints that 
you deactivated with DEACTIVATE WATCH. 

Activating and deactivating watchpoints enables you to run and rerun^your 
program with or without watchpoints without having to cancel and then reset 

them. 

By default, the RERUN command saves the current state of all static w »trfipomts 
(activated or deactivated). The state of a particular nonstatic watchpoint might or 
might not be saved depending on the scope of the variable being watched relative 
to the main program unit (where execution restarts). 

To check if a watchpoint is activated, use the SHOW WATCH command. For 
more information about watchpoints, see the SET WATCH and CANCEL WATC 

commands. 

Related commands: 

CANCEL ALL 
RERUN 

(SET,SHOW,CANCEL,DEACTIVATE) WATCH 


Examples 

i dbg> ACTIVATE WATCH SUB2\T0TAL 

This command activates the watchpoint at variable TOTAL in module SUB2. 

2. DBG> ACTIVATE WATCH/ALL 

This command activates all watchpoints you have set and deactivated. 
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ATTACH 


Passes control of your terminal from the current process to another process. 


Note 


S~ d iS " 0t a ™ ilabIe in the DEC * Mt " J Motif interface to the 


Format 


Parameters 


ATTACH process-name 


process-name 

Specifies the process to which your terminal is to be attached The process 
must already exist before you try to attach to it. If the process name contains 
nonalphanumenc or space characters, you must enclose it in quotation marks 


Description 


Examples 


The ATTACK command enables you to go back and forth between a debugging 
session and your command interpreter, or between two debugging sessions*!? 

&ST must Sp AWN command to create a subp^cesX tS 

command), you can then attach to it whenever you want To return 

comma r nd ngina Pr ° CeSS ^ minimal SyStem 0verhead ’ use another ATTACH 
Related command: SPAWN. 


1. DBG> SPAWN 
$ ATTACH JONES 

DBGfSSfSs'l 0 "” 1 retUt " ed t0 Pr °“ SS J0BES 
$ 

TnNF S q e rf mPle ; i . the /f ieS ° f commands creates a subprocess named 

tb.n ,7r a i r0n ; ^ ? ebu l gger (currentl y inning in the process JONES) and 
then attaches to that subprocess. 

2. DBG> ATTACH "Alpha One" 

$ 

This example illustrates using quotation marks to enclose a process name 
that contains a space character. 
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CALL 


CALL 


Format 


Calls a routine that was linked with your program. 


CALL routine-name [(argument^ •••])] 


Parameters 


Specifics the name or the memory address of the routine to be called. 


argument 

Specifies an 
address (the 

%ADDR 


argument required by the routine. Arguments can be passed by 
default), by descriptor, by reference, and by value, as follows: 

(Default.) Passes the argument by address. The format is as follows: 

CALL routine-name (%ADDR address-expression) 

The debugger evaluates the address expression and passes that 
address to the routine specified. For simple variables (such as X), 
the address of X is passed into the routine. This passing mechanism 
is how FORTRAN implements ROUTINE(X). In other words, for 
named variables, using %ADDR corresponds to a call by reference m 
FORTRAN. For other expressions, however, you must use the %K 
function to call by reference. For complex or composite variables 
(such as arrays, records, and access types), the address is passed 
when you specify %ADDR, but the called routine might not handle 
the passed data properly. Do not specify a literal value (a number or 
an expression composed of numbers) with %ADDR. 

%DESCR Passes the argument by descriptor. The format is as follows: 

CALL routine-name (%DESCR language-expression) 

The debugger evaluates the language expression and builds a 
standard descriptor to describe the value. The descriptor is then 
passed to the routine you named. You would use this technique o 
pass strings to a FORTRAN routine. 

%REF Passes the argument by reference. The format is as follows: 

CALL routine-name (%REF language-expression) 

The debugger evaluates the language expression and passes 
a pointer to the value, into the called routine. This passing 
mechanism corresponds to the way FORTRAN passes the result 
of an expression. 

%VAL Passes the argument by value. The format is as follows. 

CALL routine-name (%VAL language-expression) 

The debugger evaluates the language expression and passes the 
value directly to the called routine. 
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CALL 


Qualifiers 

/AST (default) 

/NOAST 

™utine. £%& £tlTttT 

the CALL command! arXTrASftTethled SP t fy ^n" /N0AST " dth 
entered the DISABLE AST commancl b d GSS y ° U haVG previousl y 

/SAVE_VECTOR_STATE 
/NOSAVE_VECTOR_STATE (default) 

statS^X^ aPPlieS *° V “ t ° J ri2ed pr0grams - Controls w hether the current 

18 SaTCd ^ • h “ • ™— - called 

The state of the vector processor comprises the following: 

' WcT^E,l t S e WR) 0r re8iSterS <V ° 10 V1K “>* «“ ''“ tor asters 

Any vector exception (an exception caused by the execution of a vector 
instruction) that might be pending delivery 

When you use the CALL command to execute a routine, execution of the routine 
might change the state of the vector processor as follows: 

By changing the values of vector registers or vector control registers 
• By causing a vector exception 

By causing the delivery of a vector exception that was pending when the 
CALL command was issued 

Jr!^ / ?^ E - VECT0R -® TATE qualifier specifies that after the called routine has 
existe teforethe CAI .1 Tf- restore ? the state “ tth * vector processor that 

“hlTcXlXx~ d " ,8SUed ™ S ^ aft ~ <*» «■»* 

VeCt °I eXC ?S 10n t J hat was P endin g delivery before the CALL command 
was issued is still pending delivery 

delivery”" 6XCepti ° n that WaS trig £ ered during the routine call is still pending 

’ ^ ide " tiCa ' 40 the ‘ r Val “ eS befcre <*» 

The /NOSAVE_VECTOR_STATE qualifier (which is the default) specifies that the 
state of the vector processor that exists before the CALL command issued is 

this 'rase F the^state , after ‘ he Ca “ ed roUtine has COI ”P lete <l execution. In 

effect (if any) the r ° Utine ““ 

Ssi N rs 01 TSe? T ?S- STATE r merS have •** « *»e general 
executes ^^0^0^ ^ ^ ~ ^ ^ 
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CALL 


Description 


actually includes a call to that routine, as long as the routine was linked w 
your program. 

When yon enter a CALL command, the debugger takes the following actions. For 
more information, see the qualifier descriptions. 

1. Saves the current values of the general registers. 

Constructs an argument list. 


2 . 

3. 


Executes a call to the routine specified in the command and passes any 
arguments. 


4. Executes the routine. 

C DisDlavs the value returned by the routine in register RO. By convention, 
after a called routine has executed, register RO contains the func ion re urn 
value (if the routine is a function) or the procedure completion status (if the 
routine is a procedure that returns a status value). If a called procedure 
does not return a status value or function value, the value in RO mig e 
meaningless, and the "value returned" message can be ignored. 

6. Restores the values of the general registers to the values they had just before 
the CALL command was executed. 

7. Issues the prompt. 

The debugger assumes that the called routine conforms to the procedure calling 
standard fsee the OpenVMS Calling Standard ). However, the debugger does no 
Cw about all the argument-passing mechanisms for all supported an^age. 
Therefore you might need to specify how to pass parameters for example, 

CALL SUB1(%VAL X) rather than CALL SUB1(X). For complete information 
about how arguments are passed to routines, see your language documentation. 

If the routine contains parameters that are not read-only, the values assigned 
to narameters may not be visible, and access to values is unreliable. Th s 
because the debugger adjusts parameter values in an internal argument list, no 
the program argument list. To examine changing values, consider using static 
variables instead of parameters. 

You can pass floating-point parameters by value in Floating fomtat. CALL 
command assumes that the floating-point value being passed is m F'Jortmg^ 
format Passing a floating-point value in a format other than F floating 
supported, and has unpredictable consequences. (See the example below.) 

A common debugging technique at an exception breakpoint (resulting from a SET 
BREAK/EXCEPTION or STEP/EXCEPTION command) is to call a dump routine 
t i PALL command When you enter the CALL command at an exception 
breakpoint an, breakpoints, tracepoints, or watchpoints that were previously set 
Sin the'called routine are temporarily disabled so that the debugger does not 
ToSe ex“ptL context. However, such eventpoints are act,ve if you enter the 
CALL command at a location other than an exception breakpoint. 
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CALL 


Alpha 


Examples 


application^declared'condition'handler^invo^T^At “ Suspe ' lded tef ' jre any 

entering a GO or STEP command after executing a rourine^fttte'^Lr 4 ’ 
commands) 811868 ' he *° resig " a ' 4ho « <see"^ EP 

teutteeta^bv k CA.'r 0 ' Aeh 7 r 41 " 68 41104 ore abated Wore the 

temma'nSLSORT 

MAIN. You must first tetum from ® ^ r ° U ‘ ine 

tte CALL c the l0gI d Cal ” a ” e ™ G «’KOCEls°tas g ?he t vatae" MLTIpSoCESsT 88 

in any 0^“ ££££ ^ SSS 

c°mman d ) are also allowed to execute. If you use the DO command to broadcast 

thP^n ^ “ u one or more Processes, the CALL command is executed in 
the context of each specified process that is not on hold but images in anv ntw 

processes that are not on hold are also allowed to execute. In alf cases a hold 
condition in the visible process is ignored. ’ 

nr-nov ar T mg mtdtl P rocess debugging configuration to debug a multiprocess 
p o^am, the way in which execution continues in your process depends on 

MOMINraRRUPT) 11 SET f ODE [N01INTERR UPT command. By default (SET 
At tw INT p RUP T-’ executl0n continues until it is suspended in any process 

irnaPM J ^ 18 interru P ted in an y other processes that were executing 
images, and the debugger prompts for input. executing 

Related commands: 

GO 

EXIT 

DO 

SET PROCESS 

SET MODE [NOJINTERRUPT 
SETVECTOR.MODE [NOJSYNCHRONIZED (VAX only) 

SYNCHRONIZE VECTOR_MODE (VAX only) 


1. DBG> CALL SUB1(X) 
value returned is 19 
DBG> 

This command calls the routine SUB1, passing the address of X as the 

IZ^ tZTT ^ de / aUlt ’ ^ addr6SS ° f the spewed is 

passed). The routine is a function whose returned value is 19. 

2. DBG> CALL SUB(%REF 1) 
value returned is 1 
DBG> 

hte~te1h“e P °Sra r 40 “ mem0,T ' 0Cati0n C °” 40mi -' 8 4he 
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CALL 


3. DBG> SET MODULE SHARE$LIBRTL 

DBG> CALL LIB$SHOW VM VM 122216 bytes 

1785 calls to LIB$GET_VM, 284 ca11s to LIB$FREE_VM, °Y 

still allocated, value returned is 00000001 
DBG> 

This example shows how you could call the run-time library routine 
LIBSSHOW VM (in the shareable image LIBRTL) to display memory 
statistics The SET MODULE command makes the universal symbo s 
(“names) in LIBRTL visible in the main image. For more information, 

see the SHOW MODULE/SHARE command. 

4 . DBG> CALL testsub (%val 11.11, %val 22.22, %val 33.33) 

This example shows how to pass floating-point parameters by value assuming 
a C subroutine with the function prototype void test s^(float,^loat, 
float). The floating-point parameters are passed in Floating format. 

5 SUBROUTINE CHECK_TEMP(TEMPERATURE,ERROR_MESSAGE) 

REAL TOLERANCE /4.7/ 

REAL TARGETJTEMP /92.0/ 

CHARACTER*(*) ERROR_MESSAGE 

IF (TEMPERATURE .GT. (TARGET_TEMP + TOLERANCE)) THEN 
TYPE *,'Input temperature out of range. ,TEMPERATU 
TYPE *,ERROR_MESSAGE 

TYPE *,'Input temperature in range:',TEMPERATURE 
END IF 
RETURN 

DBG> CALL CHECK_TEMP(%REF 100.0, %DESCR 'TOLERANCE-CHECK 1 FAILED') 

Input temperature out of range: 100.0000 

TOLERANCE-CHECK 1 FAILED 

DBG> e caa“caEc/TE«P(»I<EF 95.2, 1DESCR ■TOLERANCE-CHECK 2 FAILED’) 

Input temperature in range: 95.2000 

value returned is 0 

DBG> 

In this example, the source code is that of a FORTRAN routine (CHECK, 
TEMP) that accepts two parameters, TEMPERATURE (a rea ™ J “ 
ERROR MESSAGE (a string). Depending on the value of the temperatu , 
S roS[ne prints different output. Each of the two CALL commands passes 
a temperature value (by reference) and an error message (by descriptor). 
Because tMs routine does not have a formal return value, the value returned 

is undefined, in this case, 0. 
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CANCEL ALL 


Format 


Qualifiers 


Description 




CANCEL ALL 


/PREDEFINED 

wa^i a nts PrWleflne<1 <bUt n ° user - detoed > toeakpointe, tracepoints, and 

/USER 

» Pr ? de ' ined) break f»^. tracepoints, and 
tcnpomts. Inis is the default unless you specify /PREDEFINED. 


The CANCEL ALL command does the following steps: 

1. Cancels all breakpoints, tracepoints, and watchpoints. This is equivalent to 

CANCEL tr ace/all, !3SSSl 

A1CH/ALL commands. Depending on the type of program (for example 
Ada, multiprocess), certain predefined breakpoints or tracepoints mieht be 

mSERtTnlv ay fT y Hl Sta , rt the debuggen ^ default ^CANCEL ALL 
00 , SER) i’. * ly user -defined breakpoints and tracepoints (those you previously 
set explicitly with the SET BREAK and SET TRACE commands) and all 7 
watchpoints are canceled. If you specify /PREDEFINED but not /USFR all 

Ktntfal?ld 0 ^■ 4efi ^ d, b !i e “ a ” d 

/PlSSETOEDVSra usei - de «>«’<l breakpoints, use CANCEL ALL 

Restores the scope search list to its default value (0,1,2, . n) This is 
equivalent to entering the CANCEL SCOPE command. 

Restores the data type for memory locations that are associated with a 
compder-generated type to the associated type. Restores the type for locations 
at are not associated with a compiler-generated type to "longword integer" 

r£iiS»Sm££££5? CANCEL ™ 0VERRIDE “ d SET ' 

4 ' Sin™ 8 the Iine / symb0lic > and G.floating modes established with the SET 
following 0 command: thCir ValUeS ' ^ iS equivalent to entering the 

DBG> SET MODE LINE,SYMBOLIC,N0G_FL0AT 

The CANCEL ALL command does not affect the current language setting or 
modules included in the run-time symbol table. g 

Related commands: 


2 . 


3. 


(CANCEL,DEACTIVATE) BREAK 
CANCEL SCOPE 
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CANCEL ALL 


Examples 


(CANCEL,DEACTIVATE) TRACE 
CANCEL TYPE/OVERRIDE 
(CANCEL,DEACTIVATE) WATCH 
(SET,CANCEL) MODE 
SET TYPE 


L. DBG> CANCEL ALL 

This command cancels all user-defined breakpointsland(‘racepointe,and aH 

viuef^ 

watchpoints. 

2 %DEBUG-I-PREDEPTNOT, predefined eventpoint(s) not canceled 

This command cancels all user-defined breakpoints and tr^ 
watchnoints and restores scopes, types, and some modes to their default 
values! In this example, there are some predefined breakpoints, tracepoin , 
these are not canceled by default. 

3. DBG> CANCEL ALL/PREDEFINED 

This command cancels all predefined breakpoints, tracepoints and 
watchpoints and restores scopes, types, and some modes to their default 
values. No user-defined breakpoints or tracepomts are affected. 
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CANCEL BREAK 


Format 


Parameters 


Cancels a breakpoint. 


CANCEL BREAK [address-expression[, ... ]] 


Qualifiers 


address-expression 

t us : the a f erisk (,) 

when using any qualifiers except /EVENt! /PREDEPmED^r^SER eXpreSSi0n 

/ACTIVATING 

configuration (when DBG$PROCESS has 
/ACmlTING Jammed X nCGlS ^ ° f 3 P revious SET BREAK 

/ALL 

By default cancels all user-defined breakpoints. When used with /PREDEFTNFn 

/BRANCH 

Cancels the effect of a previous SET BREAK/BRANCH command. 

/CALL 

Cancels the effect of a previous SET BREAK/CALL command. 

/EVENT=event-name 

associated event names, use the SHOW EVENT_FACILITY command^ ^ ^ 

/EXCEPTION 

Cancels the effect of a previous SET BREAK/EXCEPTION command. 

/INSTRUCTION 

Cancels the effect of a previous SET BREAK/INSTRUCTION command. 

/LINE 

Cancels the effect of a previous SET BREAK/LINE command. 

/PREDEFINED 

/TERMINATING 

Cancels the effect of a previous SET BREAK/TERMINATING command. 
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CANCEL BREAK 


Alpha 




/UNALIGNED_DATA 

On Alpha processors, cancels the effect of a previous SET BREAK/UN ALIGNED. 
DATA command. ♦ 

Stai P mfisXSt un“ all 

user-defined breakpoints, use /ALL/USER. 

/VECTOR JNSTRUCTION 

On VAX processors, cancels the effect of a previous SET BREAK/VECTOR. 
INSTRUCTION command. ♦ 


Description 


Breakpoints can be user defined or predefined. User-defined breakpoints are 
fhoi that you set explicitly with the SET BREAK commanibSn^for 
breakpoints, w ^^^^^ u °^plj^J^ e ar e P estabhshed 1 automatically when you 
SJ& d^gerTI Sw BREAK command 1.« all breakpoints 
that are currently set. Any predefined breakpoints are identified as such. 
User-defined and predefined breakpoints are set and canceled independently 

:;^Xe”po ss*** 

breakpoint, and conversely. 

lb cancel only user-defined breakpoints, do not specify /PREDEFINED with the 
rANrEL BREAK command (the default is /USER). To cancel only predefined 
CANCEL BR /PREDEFINED but not /USER. To cancel both predefined 

/PREDEFINED and /USER. 

T 1 bVrrr ofRpf't nf the CANCEL BREAK command is symmetrical with 

SET bSI —d (even though the SET BREAK command 
1s ted oSy with user-defined breakpoints). Thus, to cancel a breakpoint 
that was established at a specific location, specify that same location (address 
expression) with the CANCEL BREAK command. To cancel breakpoints t 
were established on a class of instructions or events s 
instructions or events with the corresponding qualifier (/LINE, /BRAJNCti 
/ACTIVATING, /EVENT=, and so on). For more information, see the quail 

descriptions. 

Tf vou want the debugger to ignore a breakpoint without your having to cancel it, 
(for example if you want to rerun the program with and without breakpoin ), 
12 SSACHATE B^ instead ^ C^BREAK command. Later, 
you can activate the breakpoint (with ACTIVATE BREAK). 

Related commands: 

(ACTIVATE,DEACTIVATE) BREAK 
CANCEL ALL 
(SET,SHOW) BREAK 
(SET,SHOW) EVENT.FACILITY 
(SET,SHOW,CANCEL) TRACE 
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CANCEL BREAK 


Examples 


5 


1. DBG> CANCEL BREAK MAIN\LOOP+10 

This command cancels the user-defined breakpoint set at the 
expression MAIN\LOOP+10. P set at the address 

2. DBG> CANCEL BREAK/ALL 

This command cancels all user-defined breakpoints. 

DBG> CANCEL BREAK/ALL/USER/PREDEFINED 

This command cancels all user-defined and predefined breakpoints. 

DBG_1> CANCEL BREAK/ACTIVATING 

This command cancels a previous user-defined SET BREAK/ACTIVATINC 

nr^ h 8 \ r f Ult ; the debug ^ er does n °t suspend execution when a new 
process is brought under debugger control. 

DBG> CANCEL BREAK/EVENT=EXCEPTION_TERMINATED/PREDEFINED 

This command cancels the predefined breakpoint set on task terminations due 

fer Ada ~ - 


3. 


L 
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CANCEL DISPLAY 


CANCEL DISPLAY 


Permanently deletes a screen display. 


Note 


is command is not available in the DECwindows Motif interface to the 


This 
debugger. 


Format 


Qualifiers 


CANCEL DISPLAY [display-name[, ... ]] 


Parameters 


^rr/name of a display to »'%££££« 

Stead, usethe a Si 0 L quaSe^Do not specify a display name with /ALL. 


/ALL 

Cancels all displays, except the PROMPT display. 

Appluls^to'a'm^ip^eM'deSj^ng configuration (wh^MG$l^^CE^Uj®® 
the value MULTIPROCESS). Appends a process-identifying suffix to a disp y 
name Use this qualifier only directly after a display name. The suffix denotes 
the visible process at the time the command was issued. 

The /SUFFIX qualifier is used primarily in command procedures when you specify 
display definitions or key definitions that are bound to display definitions. 

Use any of the following process-identifier-type keywords: 

PROCESSJSTAME The display-name suffix is the process name. 

PROCESSJSTUMBER The display-name suffix is the process number (as s own 

in a SHOW PROCESS display). 

PROCESS_PID The display-name suffix is the process identification 

number (PID). 

If vou specify /SUFFIX without a process-identifier-type keyword, the P rocess 
LZe^Weused for the display-name sufib. is. by default, the same as that 
uid for the prompt suffix (see the SET PROMPT/SUFFIX command). 


Description 


men a display is canceled, its contents are j“£ fr ° m 

; he display list, and all the memory that was allocated to it is released. 

You cannot cancel the PROMPT display. 


Related commands: 

(SET,SHOW) DISPLAY 
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CANCEL DISPLAY 


(SET,SHOW,CANCEL) WINDOW 

Examples 

1. DBG> CANCEL DISPLAY SRC2 

This command deletes display SRC2. 

2. DBG> CANCEL DISPLAY/ALL 

This command deletes all displays, except the PROMPT display. 
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CANCEL IMAGE 



CANCEL IMAGE 

Deletes symbol table information for a shareable image. 


Format 

CANCEL IMAGE [image-name[, .. ■ ]] 


Parameters 




Qualifiers 

Specifies that all shareable images except the mam image are to be canceled. 


Description 


he CANCEL IMAGE cammed de^l^fteto^™^pre^bmlt 
MAGlifcommand if thTdebugger performance has slovmd do»njh*auH^ 

able (RST) without canceling the entire image. Also, y 

£ ™s or 

nodules automatically. 

hficomes the current image. 


Related commands: 

(SET,SHOW) IMAGE 

SET MODE [NOIDYNAMIC 

(SET,SHOW,CANCEL) MODULE 


Example 


DBG> CANCEL IMAGE SHARE2,SHARE3 

This command cancels shareable 
these was the current image, the 


images SHARE2 and SHARE3. If either 
main image becomes the current image. 


of 
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CANCEL MODE 




Note 


Su “” mand is not avaihble in “« DECwindows Motif interface to the 


Format 


CANCEL MODE 


Description 




Alpha 


Example 


*• CANCEL M0DE —* <• ^valent to the f„,lowing 

DBG> SET MODE LINE,SYMBOLIC,NOG FLOAT 
DBG> CANCEL RADIX ~ 

The default radix for both data entry and display is decimal for most languages 

are BLISS and ”- 32 ’ bave • 

UACR ^ 32 - and MACRO - 64 - 

Related commands: 

(SET,SHOW) MODE 
(SET,SHOW,CANCEL) RADIX 


DBG> CANCEL MODE 

This command restores the default radix mode and all default mode values. 
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CANCEL MODULE 



CANCEL MODULE 


Deletes the symbol records of a module in the current image from the run-time 
symbol table (RST) for that image. 


Note 


The current image is either the main image (bycommand 
.^Wished as the current image by a previous SET IMAGE command. 



Format 


Qualifiers 


CANCEL MODULE [module-name[, .. • ]] 


Parameters 


ISpecifiesthe^iame of a module whose symbol records are deleted from the RST. 
K use the asterisk < *) wildcard character. Instead, use the /ALL qualifier. 
Do not specify a module name with /ALL. 


Deletes the symbol records of all modules from the RST. Do not specify 
/[NOIRELATED with this qualifier. 

/RELATED (default) 

!ADn R lfe L stoAda programs.) Controls whether the debugger deletes from the RST 
ihe^bol Records ^5 a module that is related to a specified module through a 
with-clause or subunit relationship. 

The CANCEL MODULE/RELATED command deletes symbol records for related 

with^Ada’s »cop e a ^^c^^™MODUIJ^O^E^rai^<»nm^d^deletes 
SX, n re^i only for modules that are specified (no symbol records are deleted 
for related modules). 


Description 


e the CANCEL MODULE command if the debugger performan^h^s slowed 

f^y^^bleTiSthTe'MODE NODYNAMIC command. As a 
suit, the debugger does not set modules or images automatically. 

ie CANCEL MODULE command does not cancel any breakpoints, tracepoints, 
watehpofnts that are set currently. It deletes the symbolization of any 
eakpoints, tracepoints, or watchpoints associated with the canceled modu . 
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CANCEL MODULE 


Related commands: 

(SET,SHOW,CANCEL) IMAGE 
SET MODE [NOJDYNAMIC 
(SET,SHOW) MODULE 

Examples 

1 . DBG> CANCEL MODULE SUB1 

This command deletes the symbols of module SUB1 from the RST. 

2. DBG> CANCEL MODULE/ALL 

This command deletes the symbols of all modules from the RST. 
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CANCEL RADIX 



CANCEL RADIX 

Restores the default radix for the entry and display of integer data. 


Format 


Qualifiers 


CANCEL RADIX 


Cancels the override radix established by a previous SET RADIX/OVERRIDE 
eo" sets the current override radix to -ngj 

radix mode to the value established with a previous SET RADIX or SE1 
/OUTPUT command. If you did not change the radix mode with a SET RADIX 
"set MIX/OUTPUT command, the CANCEL RADIX/OVERRIDE command 
restores the radix mode to its default value. 


Description 




Alpha 


Tie CANCEL RADIX command cancels the effect of any previous SET EAD 
nd SET RADIX/OVERRIDE commands. It restores the input and output radix to 
heir default value. The default radix for both data entry and display is dec 


for most languages. 

On VAX processors, the exceptions are 
default radix of hexadecimal. ♦ 


BLISS and MACRO-32, which have a 


On Alpha processors, the exceptions are BLISS, MACRO-32, and MACRO 64, 
which have a default radix of hexadecimal. ♦ 


The effect of the CANCEL RADIX/OVERRIDE command is more limited and is 
explained in the description of the /OVERRIDE qualifier. 


Related commands: 


EVALUATE 
(SET,SHOW) RADIX 


Examples 

1. DBG> CANCEL RADIX 

This command restores the default input and output radix. 

2. DBG> CANCEL RADIX/OVERRIDE 

This command cancels any override radix you might have set with the SET 
RADIX/OVERRIDE command. 
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CANCEL SCOPE 


CANCEL SCOPE — 

Restores the default scope search list for symbol lookup. 

Format 


CANCEL SCOPE 

Description 


by a previous*SE'^SCOR e'co ^ CUrren * Bc<,pe seareh list ^btohed 

."r,T bET SC0PE command and restores the default scope search list 

y , ,2, ... ,n, where n is the number of calls in the call stack 

ShekaUtwsSTtebMGOT)! S“ me Symb0 ‘ (EST) ' 

Related commands: (SET,SHOW) SCOPE. 


Example 


DBG> CANCEL SCOPE 

This command cancels the current scope. 
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CANCEL SOURCE 


CANCEL SOURCE 


Format 


Qualifiers 


Cancels a source dirertory search list, a source ^ * 

list and method established by a previous SET SOURCE command. 


CANCEL SOURCE 


(Applies mainly to Ada programs.) Cancels the effect of a previous SET SOURCE 
/EDIT command which specifies the directory search list to be used during 
STrfSe dliggert EDIT command. Canceling this command means the 
dS^er searches for a source file in the directory in which it was comp,led. 

Cancels the effect of a previous SET SOURCE/EXACT command, which specifies 
a directory search method. Canceling this command means that the debugger no 
b^er seiches for the exact version of the source file from comp! ation; it reverts 
to the default behavior of searching for the latest version of the file. 

Ca™* T the effect of a previous SET SOURCE/™ —4wWch specifies 
a directory search method. In this case, the CANCEL SOURCE/LAi 
Ltmand directs the debugger to return to searching for the exact version of 
rrlSrlpiScu Because /LATEST is the default setting, this 
qualifier only makes sense when used in conjunction with other qualifiers, for 
example, /MODULE. 

Cfmw^to^eff&it^if a'previous SET S0D^CE/M0DULE=mMfule-nctme^i^i^i^ 

qiemh^aL^riET ^CEMODU^nd CANCEL SOURCE 
/MODULE commands. 

Tf vou issue a CANCEL SOURCE/MODULE command with additional qualifiers, 
vou canceUhe^ effort of the specified qualifiers on the module. If you issue an 
unqualified CANCEL SOURCE/MODULE command, the debugger no longer 
differentiates the module from any other module in your irec ones. 

(Applies to STDL programs only. Requires the installation ^ 

Facility (a separate layered product) and invocation of^the Kept Debugger.) 
Cancels the effect of a previous SET SOURCE/ORIGINAL command. The SET 
SOURCE/ORIGINAL command is required to debug STDL source files, an mus 
be canceled when you debug source files written in other languages. 
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CANCEL SOURCE 


Description 


Examples 


CANCEL SOURCE cancels the effect of a previous SET 1 ^OTiRPi? j mi 

SOURCE tWS CanC f lla £ ion de P ends on th e qualifiers activated^in preXuTsET 
oOURCE commands. See the CANPFT i , vious on<i 

SOURCE and SET SOURCEinteract ” PleS 10 “* h ° W CANCEL 

^aMe"^TES S Tl S ™cT “T? 4 be aware * hat ‘wo 

fhA HoK /LATEST or /EXACT—will always be active. These qualifiers affect 
the d eb ugge r search method. The /LATEST qualifier directs the debuSL 

tecw The *MCT las ;rr ^Bhest-numbured version in your 
directory) the /EXACT qualifier directs the debugger to search for the verson 

ast compiled (the version recorded in the debugger symbol table created at 
J!riT? IT ?T lifier u iS needed when the files used for the display of source code 

commanfis^affec^ffirs^ardi 1 !)^ 3 

so 6 (S ^’S®^^ l ^A^^I^^SOlJRCEyEDI r ^commar^s^affec a thTsearch^of^he 8 ^' 

source files that you edit when using the EDIT command. 

For information specific to Ada programs, type HELP Language ADA. 

Related commands: 

(SET,SHOW) SOURCE 


l. 


DBG> SET SOURCE/MODULE=CTEST/EXACT [], SYSTEM--DEVICE-rPROTni 
DBG> SET SOURCE [PROJA],[PROJB],[PETER.PROJC] 1 

DBG> SHOW SOURCE 

source directory search list for CTEST, 
match^the exact source file version: 

SYSTEM::DEVICE:[PROJD] 

source directory list for all other modules, 
match the latest source file version- 
[PROJA] 

[PROJB] 

[PETER.PROJC] 

DBG> CANCEL SOURCE 
DBG> SHOW SOURCE 

source directory search list for CTEST, 
match^ the exact source file version: 

SYSTEM::DEVICE:[PROJD] 
all other source files will try to match 
the latest source file version 

In this example the SET SOURCE command establishes a directoiy search 

thl cTES?T?^ lat6St Versi ° n) for Source files oth er 

list hnt T d E n ST ' CA ^^ L SOURCE command cancels the directoiy search 
list but does not cancel the search method. 
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CANCEL SOURCE 


2 DBG> SET SOURCE/MODULE=CTEST/EXACT [],SYSTEM::DEVICE:[PROJD] 
2 ' npc, crt SOURCE [PROJA], [PROJB], [PETER.PROJC] 


DBG> SHOW SOURCE 

source directory search 
match the exact source 


list for CTEST, 
file version: 


SYSTEM::DEVICE:[PROJD] 

source directory list for all other modules, 
match the latest source file version: 

[PROJA] 

[PROJB] 

[PETER.PROJC] 


DBG> CANCEL SOURCE/MODULE=CTEST/EXACT 
DBG> SHOW SOURCE 

source directory search list for CTEST, 
match the latest source file version: 


SYSTEM::DEVICE:[PROJD] 

source directory list for all other modules, 
match the latest source file version: 

[PROJA] 

[PROJB] 

[PETER.PROJC] 

DBG> CANCEL SOURCE/MODULE=CTEST 

dbg> show source 

source directory list for all modules, 
match the latest source file version: 
[PROJA] 

[PROJB] 

[PETER.PROJC] 


In this example, the SET SOURCE/MODULE=CTEST/EXACT command 

establishes a directory search list aad a aaa “S TJ™??, SSeST/EXACT 
the source file CTEST. The CANCEL SOURCE/MODULE-CTEST/EXALl 
command cancels the CTEST search method (returning to the default latest 
“Sn>, and the CANCEL SOURCE/MODULE=CTEST command cancels the 
CTEST directory search list. 


3. 


dbg> set source /exact 
dbg> show source 

no directory search list in effect, 
match the exact source file 
DBG> SET SOURCE [JONES] 

DBG> SHOW SOURCE 

source directory list for all modules, 
match the exact source file version: 
[JONES] 

DBG> CANCEL SOURCE /EXACT 
DBG> SHOW SOURCE 

source directory list for all modules, 
match the latest source file version: 


[JONES] 

In this example, the SET SOURCE/EXACT “ m “ a ” d “ ^Se S] 

method (exact version) that remains in effect for the SET SOURCE IJUrmsj 
command. The CANCEL SOURCE/EXACT command nc*»nly “ance^SET 
SOURCE/EXACT command, but also affects the SET SOURCE LJONhbJ 
command. 
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CANCEL TRACE 


CANCELTRACE 


Cancels a tracepoint. 


Format 

CANCEL TRACE [address-expression[, 

Parameters 


]] 


Qualifiers 


address-expression 

Specifies a tracepoint to be canceled. Do not use the asterisk (*) wildcard 
character. Instead, use the /ALL qualifier. Do not specify an address expression 
when using any qualifiers except /EVENT, /PREDEFINED, or /USER. 

/ACTIVATING 

tfng , /"' hen DBG$PEOCESS has 

/ACTIVATINGTmmand pre ™ us SET TEACE 

/ALL 

R y canSlt 1 !;i? anC !! S fl all -i 1 ! er ' defined trace P° ints - When used with /PREDEFINED 
it cancels all predefined tracepoints but no user-defined tracepoints. To cancel all 

tracepoints, use/ALL/USER/PREDEFINED. 10 cancel all 

/BRANCH 

Cancels the effect of a previous SET TRACE/BRANCH command. 

/CALL 

Cancels the effect of a previous SET TRACE/CALL command. 

/EVENT=event-name 

Sn^ C if 1S ^ he effe ? of a P revious SET TRACE/EVENT= e[ /en/-/iam e command 

the SET'tRACE/EVFNT 311 addrass expression, if any) exactly as specified with 
the SET TRACE/EVENT command. To identify the current event facility and the 
associated event names, use the SHOW EVENTFACILITY command. 

/EXCEPTION 

Cancels the effect of a previous SET TRACE/EXCEPTION command. 


/INSTRUCTION 

Cancels the effect of a previous SET TRACE/INSTRUCTION command. 


/LINE 

Cancels the effect of a previous SET TRACE/LINE command. 

/PREDEFINED 


Cancels a specified predefined tracepoint without affecting 
tracepoints. When used with /ALL, it cancels all predefined 


any user-defined 
tracepoints. 


/TERMINATING 

Cancels the effect of a previous SET TRACE/TERMINATING command. 
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CANCEL TRACE 



/ USER 

Cancels a specified user-defined tracepomt 
tracepoints. This is the default unless you 
user-defined tracepoints, use /ALL/USER. 


without affecting any predefined 
specify /PREDEFINED. To cancel all 


/VECTOR JNSTRUCTION 

On VAX processors, cancels the effect of a previous SET TRACE/VECTOR. 
INSTRUCTION command. ♦ 


Description 


Tracepoints can be user defined or predefined. User-defined tracepoints are 
explicitly set with the SET TRACE command. Predefined tracepoints, which 
depend on the type of program you are debugging (for example Ada or 
multinrocess), are established automatically when you start the debugger. 

Use the SHOW TRACE command to identify all tracepoints that are currently 
set. Any predefined tracepoints are identified as such. 

User-defined and predefined tracepoints are set and canceled independently. 
FoTexampfe. a location or event can have both a user-defined and a predefined 
tracepoint. Canceling the user-defined tracepomt does not affect the prede 
tracepoint, and conversely. 

To cancel only user-defined tracepoints, do not specify /PREDEFINED with the 
CANCEL TRACE command (the default is /USER). To cancel only predefin 
tracenoints specify /PREDEFINED but not /USER. To cancel both user-defined 
and predefined^tiacepoints, use CANCEL TRACE/ALL1USER/PREDEFINED. 

In general, the effect of CANCEL TRACE is symmetrical with that of SET 
TRACE (even though SET TRACE is used only with user-defined tracepoints). 
Thus to cancel a tracepoint that was established at a specific location, specify 
SLTiame location (address expression) with CANCEL TRACE. To .cancel 
tracepoints that were established on a class ofinstructions °r e™nts ! 
class of instructions or events with the corresponding qualifier (/LINE, ^^ CH ’ 
/ACTIVATING, /EVENT=, and so on). For more information, see the quaimer 

descriptions. 

Tf vou want the debugger to ignore a tracepoint without your having to cancel it, 
(for example, if you want to rerun the program with and without tracepoints), use 
the DEACTIVATE TRACE instead of the CANCEL TRACE command, a er, you 
can activate the tracepoint (with ACTIVATE TRACE). 


Related commands: 

(ACTIVATE,DEACTIVATE) TRACE 
CANCEL ALL 

(SET,SHOW,CANCEL) BREAK 
(SET,SHOW) EVENT_FACILITY 
(SET,SHOW) TRACE 


Examples 

1. DBG> CANCEL TRACE MAIN\LOOP+10 

This command cancels the user-defined tracepoint at the location 
MAIN\ LOOP+10. 
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CANCEL TRACE 


3. 


2. DBG> CANCEL TRACE/ALL 

This command cancels all user-defined tracepoints. 

DBG_1> CANCEL TRACE/TERMINATING 

Sa "rllSS “ J? Vi ° US SET ^^TERMINATING command, 
image ert USer ' deflned trace l> omt 18 Mggered when a process does an 

4. DBG> CANCEL TRACE/EVENT=RUN %TASK 3 

that was 861 *° **■-—** * 
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CANCEL TYPE/OVERRIDE 



CANCEL TYPE/OVERRIDE 

Cancels the override type established by a previous SET TYPE/OVERRIDE 


command. 

Format 

CANCEL TYPE/OVERRIDE 


Description 


The CANCEL TYPE/OVERRIDE command sets the current override type to 

a result, a program location associated with a compder-generated type 

is interpreted according to that type. 


Related commands: 

DEPOSIT 

EXAMINE 

(SET,SHOW) EVENT_FACILITY 
(SET,SHOW) TYPE/OVERRIDE 


Example 


dbg> cancel type/override 

This command cancels the effect of a previous SET TYPE/OVERRIDE command. 
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CANCEL WATCH 


CANCEL WATCH 


Format 


Parameters 


Cancels a watchpoint. 


CANCEL WATCH [address-expressionf, ... ]] 


Qualifiers 


Description 


address-expression 

uae the /ALL qualffler. Do not specify an address eipressfon w» Si'. ^ 


/ALL 

Cancels all watchpoints. 


C r mand iS ^trical with the effect of 

° f - “aiS “ 

The CANCEL ALL command also cancels all watchpoints. 

If you want the debugger to ignore a watchpoint without your having to cancel it 

use the a DEACTWATrWA t T 0 rR rUn ^7^“ With and without watchpoints), 
use tne DKAL HVATE WATCH instead of the CANCEL WATCH command T **«. 

you can activate the watchpoint (with ACTIVATE WATCH) ’ 

Related commands: 


(ACTIVATE,DEACTIVATE) WATCH 
CANCEL ALL 

(SET,SHOW,CANCEL) BREAK 
(SET,SHOW,CANCEL) TRACE 
(SET,SHOW) WATCH 

Examples 

1. DBG> CANCEL WATCH SUB2\T0TAL 

This command cancels the watchpoint at variable TOTAL in module SUB2. 

2. DBG> CANCEL WATCH/ALL 

This command cancels all watchpoints you have set. 
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CANCEL WINDOW 



CANCEL WINDOW 


Permanently deletes a screen window definition. 

_ Note - 


i, command is not available in the DECwindows Motif interface to the 


This 
debugger. 


Format 


CANCEL WINDOW [window-name[, ... ]] 


Parameters 


window definition name with /ALL. 


Qualifiers 


/ALL 

Cancels all predefined and user- 


defined window definitions. 


Description 


When a window definition is canceled, you can no longer use its name in a 
DISPLAY command. The CANCEL WINDOW command does not affect any 

displays. 

Related commands: 


(SET,SHOW,CANCEL) DISPLAY 
(SET,SHOW) WATCH 


Example 


DBG> CANCEL WINDOW MIDDLE 

This command permanently deletes the screen window definition MIDDLE. 
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CONNECT 


Alpha 


Format 


Parameters 


and brings that PTOeiTmde^Sng^r contro^-Kn us"d”' ? h a T ther process 

DBG$PROCESS^ias e the**v^ue 0 MULTIPROC^S£b* JU ^ n ^d C f n ^f Urat * 0n ^ w ^ en 

command^ 00 " *» 

*rzzz al Jtz T iss ^ the “• %££E£Z?£S 

the OpenWS , Ta r. a " d the "*» “-^nds activating 

OpenVMS D^5KS£S& , ( J|1^ I* ^ — «" 


CONNECT [process-spec] 

CONNECT %NODE_NAME node-name 


process-spec 

^“? eSa process in which an image to be interrupted is running The process 
started 6 ™ ^ the **»" "* 


[%PROCESS_NAME] proc-name 


[%PROCESS_NAME] " proc-name * 


%PROCESS_PID proc-id 


node-name 


The OpenVMS process name, if that 
name contains no space or lowercase 
characters. The process name can 
include the asterisk (*) wildcard 
character. 

The OpenVMS process name, if that 
name contains space or lowercase 
characters. You can also use 
apostrophes (') instead of quotation 
marks ("). 

The OpenVMS process identification 
number (PID, a hexadecimal number). 


Alpha 


the nIdo a nf^ temS ’ r he V°V re debu £gi n g the Alpha operating system specifies 

£ SS y ° U ” — «» targetVachine ■££ 
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CONNECT 


Qualifiers 


Alpha 


Description 


/PASSWORD="password" 

that machine, this qualifier can be omitted. 

£3 fte Edition is DBGHK$IMAGE_ 

PATH:. ♦ 

process under debugger control The p ^m 

“Ta bS^ romtime u“all that does not start the debugger You 
rrconne”r^ created through a $CREPRC system service call. 

Depending on the version of the debugger you are running on your system 
may be restricted to connection with processes you created or you “ a y be ab 
connect to processes created by any member of youruser,itattowt* 

that apply to specific versions of the debugger. 



Version 6.1 
Version 6.2 


Yourself 
Yourself 
Yourself, Member of 
UIC Group 
Yourself, Member of 
UIC Group 
Yourself, Member of 
UIC Group 


No 


No 


VMSDEBUGUIL) must translate to the same definitions for both debugg 
and target process. 

qualifier^Th^hm^e^annot^dave^eenh^e^v^th ^OT^CEBACKqualifier. 
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CONNECT 


Alpha 


Examples 


Sw« , ,Tn i! b r'! gh !. U I* r debUgger COntro1 ’ “““‘ion of the image is 
suspended at the point at which it was interrupted. 

tW e ai°wS n0t f SPeCify 3 Pr ° CeSS ’ the C0NNEC T command brings any processes 
no nrnro . ltin ^^° connect to your debugging session under debugger control If 
process is waiting, you can press Ctrl/C to abort the CONNECT Command' 1 

tra !f« 0in j 1S tnggered when a Process is brought under debugger 
the SET tSaCTIV^ 

debugger and can be identified in a SHOW PROCESS display. 

You cannot use the CONNECT command to connect to a subprocess of a nrocess 
™a n !u U bpr»ess ^ “” tr01 ' 1,16 SET PR0CESS to connect to 

Using the CONNECT Command to Debug the Alpha Operating System 

On Alpha systems, you can use the CONNECT command to debug Alnha 

AlnS, tmg t ySte T COde ' ^ picall y’ y° u issue this command from a timesharing 
Alpha machine (running the debugger), and you connect to a standaToneXha 

machine (running the Alpha operating system). Communication between the two 
machines occurs over the Ethernet network. between tne two 

In some cases, you may find that you need to use the less-robust Delta/XDelta 
Debugger to debug operating system code. These cases include: 

When you have access to only one Alpha machine for debugging 

When you are debugging portions of code that generate Ethernet traffic on 
the target system. (This now causes the target system to fail, but will be 
corrected m a future release.) 

GeneraUy.however, the OpenVMS Alpha System-Code Debugger is the preferred 
debugger for debugging Alpha operating system code. For complete infomatSn 
on using this debugger, see the OpenVMS Alpha Device Support Manual. . 

Related commands: 

DISCONNECT 

Ctrl/Y 

(SET,SHOW,CANCEL) TRACE 


1. DBG_1> CONNECT 

Tu er debugger contro1 an y processes that are waiting 
to be connected to the debugger. ® 

2. DBG_1> CONNECT JONES 3 

This command interrupts the image running in process JONES.3 and brings 
the process under debugger control. Process JONES_3 must be in the same 

S aS u e pr ? ce rj n Which the debugg er was started. Also, the image 
must not have been linked with the /NOTRACEBACK qualifier. g 

3 ' %DEBUG-I N NoLS?f- NAME tin 5- node /PASSWORD="eager beaver" 

DBG> UG 1 N0L0CALS ' ima 9 e does not contain local symbols 
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CONNECT 


Alpha 


On Alpha systems, this CONNECT command brings the 

rinino* Alpha operating-system code under debugger contro . V 

specifies that the Alpha target machine (running the gating sjJenO has a 
node name of testing_node and a Password of ^teaver^e A,pha host 
machine (running the debugger) has the default DBGHK$IMAt^_mirt. 
image-path. ♦ 
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Ctrl/C 


WJen entered from within a debugging session, Ctrl/C aborts the execution of 
debu6gSg r sSZ ° r mterrUPtS Pr °^ m e “ CUti0n with0l “ interrupting the 


Note 


Do not use Ctrl/Y from within a debugging 


session. 


Format 


[Ctrl/C | 


Description 


hZZuvtmoLT l t the execution of a debugger command or to 
mterru p t p rogram execution without interrupting the debugging session This is 

hat?! h her t f ° r f ample ’ the program is executing an infinite loop that does not 
H , reakpoint, or you want to abort a debugger command that takes a long 

debugger prompt is then ^ 

SS5S 2i r ltipr ” ess program that 

ABORT P KFY m alread J has a Ctrl { C AST service routine enabled, use the SET 
ABORT_KEY command to assign the debugger’s abort function to another Ctrl- 
key sequence. Note, however, that many Ctrl-key sequences have predefined* * 
functions, and the SET ABORT_KEY command enables you to ovemde such 
e nitions (see the OpenVMS User’s Manual ). Some of the Ctrl-key characters 
not used by the operating system are G, K, N, and R 

If your program does not have a Ctrl/C AST service routine enabled and you 

bSe! 4?CMS rS th b t 0rt f > nCt i° n t0 an ° ther ° trl ' key SeQUence ’ then Ctrl/C 

to DCL level. C W ha 1S ’ mterrupts the dehu Sging session and returns you 

Do not use Ctrl/Y from within a debugging session. Instead, use either Ctrl/C 

or an equivalent Ctrl-key sequence established with the SET ABORT KEY 
command. - 

You can use the SPAWN and ATTACH commands to leave and return to a 
debugging session without losing the debugging context. 

Related commands: 

ATTACH 

Ctrl/Y 

(SET,SHOW) ABORT.KEY 
SPAWN 
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Ctrl/C 


Example 


DBG> GO 


DBG> EXAMINE/BYTE 1000:101000 
1000 : 0 
0 
0 
0 
0 

jewel 

%debug-w-aborted 


'.should have typed 1000:1010 


1004: 

1008: 

1012: 

1016: 


rnmmand aborted by user request 


DBG> 

This example shows how to use Ctrl/C to interrupt program 
to abort the execution of a debugger command. 


execution and then 
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Ctrl/W 


Ctrl/W 

Format 

Description 


Ctrl/W refreshes the screen in screen mode (like DISPLAY/REFRESH). 

| Ctrl/W | 

For more information about Ctrl/W, see the DISPLAY/REFRESH command. 
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Ctrl/Y 



Ctrl/Y 


When entered from DCL level, Ctrl/Y interrupts an image 
debugger control, enabling you then to start the debugger 


that is running without 
with the DCL command 


DEBUG. 


Notes 


Do not use Ctrl/Y from within a debugging session.^ qRT KEY 
an equivalent abort-key sequence established with the SET ABOKl.luti 

pnmmand. 


When you start the debugger with the 
cannot then use the debugger RUN or 


Ctrl/Y-DEBUG sequence, you 
RERUN commands. 


Format 


[Ctri/Yl 


Description 


Pressing Ctrl/Y at DCL level enables you to interrupt an image that is running 
without*debugger control, so that you can then start the debugger with the DCL 

command DEBUG. 

You can bring an image under debugger control only if, as a minimum, that 
image was linked with the /TRACEBACK qualifier (/TRACEBACK is the defau 
for the LINK command). Also, you can reference all of the images 

while debugging only if its modules were compiled and lm ^ d ^ebuG to 
qualifier (in that case, you would use the DCL command RUN/NODEBUG to 

execute the image without the debugger). 

When you press Ctrl/Y to interrupt the image’s execution, control is passed to 
DCL If you then type the DCL command DEBUG, the interrupted image is 
brought under control of the debugger. The debugger sets its language-dependent 
parameters to the source language of the module in which execution was 
interrupted and displays its prompt. You can then determine whereexecuLo^ 
was suspended by entering a SHOW CALLS command (and a SHOW PROCESS 
command, in the case of a multiprocess program). 

Other details about the effect of a Ctrl/Y-DEBUG sequence depend on the 
debugging configuration (default or multiprocess), which is determined by the 
^Sdefinitio^of the logical name DBG$PROCESS in the process where the 

interrupted image was executing. 

The Ctrl/Y-DEBUG sequence is not supported in the Kept Debugger 
configuration. 

The Ctrl/Y-DEBUG sequence is not supported in the DECwindows Motif interface 
to the debugger. Instead, use the STOP button. 
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Ctrl/Y 


Examples 


Default Debugging Configuration 

da fi*nlt debugging configuration is achieved when DBG'ftPROPTi'QQ • *,i 

se^ionS started‘ he b *“• 

sequence (see Exampte l'™ ^ “** ““ debugger with ‘he Ctr]/Y-DEBUG 

Multiprocess Debugging Configuration 

The multiproeess debugging configuration is achieved when DBG$PROCFSS w 

^tTZlf T,PR0CESS - In thls ‘ ba -*«* Sr 

11 * multiprocess debugging session does not already exist in the same iob 

sssr imase ’* new ->“~xSn g 

?ntl mUl ^ r ° CeSS debl ! gging sessi0n alread y e ^sts in the same job the 

case tbfd d h image r d ltS P ? C6SS COme under contro1 of that session. In this 
case the debugger does not display its banner. 

,v!!t in +K d f ebugging session > you can use the CONNECT command to connect an 

debugger contro1 in another 

Related commands: 

CONNECT 

Ctrl/C 

DEBUG (DCL command) 

RUN (DCL command) 


1. $ RUN/NODEBUG TEST B 


|ctri/Y| 
Interrupt 
$ DEBUG 


Debugger Banner and Version Number 


DBG> UG ~ I ~ INITIAL ' language is ADA ' m °dule set to SWAP 

SSZ'E** the ^ / N 0DEB “ command executes the image TEST B 

command then causes the debugger to be started. The debugger displays its 

Le) <Jth?modae”ffiTOp1 eP<!n h en h parameters ‘° ‘he tankage (Ada, in this 
case; ot the module (SWAP) in which execution was interrupted and disnlavs 

DBG>°prompt * * ^ defeult debugging configuration, as indicated by the 
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Ctrl/Y 


2 $ DEFINE/JOB DBG$PROCESS MULTIPROCESS 

$ RUN/NODEBUG PROG2 


[Ctrj/Y| 

Interrupt 
$ DEBUG 


Debugger Banner and Version Number 


DBG_1> 

In this example, the DEFINE/JOB command establishes a multiprocess 
debugging configuration. The RUNiNODI^UG cornmand e^recutes the 

image PROG2 without debugger control. The Ctrl/Y DEBU q 
interrupts execution and starts the debugger The banner inmates that 
a new debugging session has been started. The process-specific pro p 
(DBG_1>) indicates that this is a multiprocess configurationandthat 
execution is suspended in process 1, which is running PROG2. The activation 
tracepoint indicates where execution was interrupted when the debugger took 
control of the process. 
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Ctrl/Z 


Ctrl/Z -- 

Ctrl/Z ends a debugging session (like EXIT). 

Format 

[Ctri/Zl 

Description 

For more information about Ctrl/Z, see the EXIT command. 
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DEACTIVATE BREAK 


DEACTIVATE BREAK 

Deactivates a breakpoint, which you can later activate. 


Format 


DEACTIVATE BREAK [address-expression[, . .. ]] 


Parameters 


Qualifiers 


STfilt to be deactivated. Do not use the asterisk (*) wildcard 
character Instead, use the /ALL qualifier. Do not specify an address expression 
Jhen ^liig any qualifiers except /EVENT, /PREDEFINED, or /USER. 


A^irramultiprocess debugging configuration (whenp«*«OCB»ihas; the 
value MULTIPROCESS). Deactivates a breakpoint established by a previous S 
BREAK/ACTIVATING command. 

^default, deactivates all user-defined breakpoints. When used with 
/PREDEFINED, it deactivates all predefined breakpoints bifiM^iser-d fi d 
breakpoints. To deactivate all breakpoints, use /ALL/USER/PREDEr 

Deactivates a breakpoint established by a previous SET BREAK/BRANCH 
command. 

Deactivates a breakpoint established by a previous SET BREAK/CALL command. 

Dea^tivate^a^breakpoint established by a previous SET BREAK/EVENT=ci>eni- 
name command. Specify the event name (and address expression, if any) exactly 
as specified with the SET BREAK/EVENT command. 

To identify the current event facility and the associated event names, use the 
SHOW EVENT_FACILITY command. 

Deactivates^! breakpoint established by a previous SET BREAK/EXCEPTION 
command. 

DeaJtiva te T s abreakpoint established by a previous SET BREAK/INSTRUCTION 
command. 

Deartivates a breakpoint established by a previous SET BREAK/LINE command. 

Deactivates^specified predefined breakpoint without affecting any user-defined 
breXotots. ^hen used with /ALL, it deactivates all predefined breakpoints. 
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DEACTIVATE BREAK 


/TERMINATING 

commanT 8 & breakpomt established by a previous SET BREAK/TERMINATING 

/UNALIGNED_DATA 


Alpha 


Description 


BREAK^NALIGNED^IL\TA a command ak r 0mt eStabHshed by a previous SET 

/USER 

breTkToints.^en 1 ^ustd withMLL deTt^ 0 ^ W j khout effecting any predefined 
/USER qualifier is the default unles’s you The 

/VECTORJNSTRUCTION 

r “ 8hed by a — set 


Examples 


BRFAK^ break P° in <; s are activated when you set them with the SET 

DEACTIVATE BREAK defined braakpoints are activated by default. Use the 
utiiACllVATE BREAK command to deactivate one or more breakpoints. 

irn^,i eaCtlVa + te a b " eakp0int ’ the debu gger ignores the breakpoint during 

BRFAK Utl0n - J° activate a deactivated breakpoint, use the ACTIVATE 

BREAK command. You can activate and deactivate user-defined and predefined 

breakpoints separately. Activating and deactivating breakpoints enables vou 

™ ST y ° Ur program with or without breakpoints without having to 

stTlf ,1 K en , reSet tbem ' % d6fault ’ the RERUN command saves the current 
state of all breakpoints (activated or deactivated). 

To check if a breakpoint is deactivated, use the SHOW BREAK command For 
™mmands matl ° n breakpoints ’ see SET BREA * and CANCEL BREAK 

Related commands: 

CANCEL ALT, 

RERUN 

(SET,SHOW,CANCEL,ACTIVATE) BREAK 
(SET,SHOW) EVENT_FACILITY 


1. DBG> DEACTIVATE BREAK MAIN\LOOP+10 

This command deactivates the user-defined breakpoint set at tha aH,Wo 
expression MAIN\ LOOP+IO. P at the address 

2. DBG> DEACTIVATE BREAK/ALL 

This command deactivates all user-defined breakpoints. 
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DEACTIVATE TRACE 


DEACTIVATE TRACE 


Deactivates a tracepoint, which you can later activate. 


Format 


DEACTIVATE TRACE [address-expression[, ... ]] 


Parameters 


Qualifiers 


SSETSSjSt to be deactivated. Do not use the asterisk, *) wildcard 
character. Instep, use the /ALL qualifier. Do not spec* an address eapressio 
when using any qualifiers except /EVENT, /PREDEFINED, or /USER. 


Afplir™ G multiprocess debugging configuration.(whenJ.DDOWROCESSta the 
value MULTIPROCESS). Deactivates a tracepoint established with a previo 
SET TRACE/ACTIVATING command. 

Bvdefault deactivates all user-defined tracepoints. When used with 
/PREDEFINED, it deactivates all predefined 

tracepoints. To deactivate all tracepoints, use /ALL/USER/PREDhr IN . 

Deactivates a tracepoint established with a previous SET TRACE/BRANCH 
command. 

Deactivates a tracepoint established with a previous SET TRACE/CALL 
command. 

SIXT^rint established with a previous SET TRACE/EVENTWuenl- 
name command. Specify the event name (and address expression, if any) exactly 
as specified with the SET TRACE/EVENT command. 

To identify the current event facility and the associated event names, use the 
SHOW EVENT_FACILITY command. 

Deactivates^ tracepoint established with a previous SET TRACE/EXCEPTION 
command. 

DeaJtivate^ atracepoint established with a previous SET TRACE/INSTRUCTION 
command. 

Deactivates a tracepoint established with a previous SET TRACE/LINE 
command. 
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DEACTIVATE TRACE 


Description 


/PREDEFINED 

£5= sssaa.ass*a~!- 

/TERMINATING 

OTMNATING a Xmand S “ iShe<i ” th “ PreVi0US SET 

/USER 

tZpZZ ~~ af&Ctin8 any predeltaed 

Tho /TTQTTro 1 * , h /ALL > lfc deactivates all user-defined tracenoints 
qualifier is the default unless you specify /PREDEFINED. 

/VECTORJNSTRUCTION 

>Ushed a “ set 


Examples 


THArr!r d * ra “ p " int ? are activated when you set them with the SET 

DEACTreSE a TRACTe *™cepoints are activated by default. Use the 
UVATE TRACE command to deactivate one or more tracepoints 

InZmZeZuUon ‘t T mt ; th ° ieb ^ *“"• tb ° ‘cacepoint during 
TRATF mm j V activate a deactivated tracepoint, use the ACTIVATE 
RACE command. You can activate and deactivate user-defined and Dredefined 
tracepoints separately. Activating and deactivating tracepoints enables vou to 

and thenrZ t Cn* B^aSfthe MRTO haVinB 10 CanCel 

_n j . . ’ y aeiauit, tne Ki^KUN command saves the current ctatp nf 

all tracepoints (activated or deactivated). current state of 

To check if a tracepoint is deactivated, use the SHOW TRACE command For 
“mmandr^ 1011 ***”* traCepoints ’ see the SET TRACE and CANCEL TRACE 

Related commands: 

CANCEL ALL 
RERUN 

(SET,SHOW) EVENT_FACILITY 
(SET,SHOW,CANCEL,ACTIVATE) TRACE 


1 DB G> DEACTIVATE TRACE MAIN\LOOP+10 

SSn\ W^l d o eaCtiVateS 0,6 USer - delb,ed ‘ ra «POint at the location 

2. DBG> DEACTIVATE TRACE/ALL 

This command deactivates all user-defined tracepoints. 
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DEACTIVATE WATCH 


DEACTIVATE WATCH 


Deactivates a watchpoint, which you can later activate. 


Format 


DEACTIVATE WATCH [address-expression[, .. ■ ]] 


Parameters 


SIS 

£3 use the /ALL qualifier. Do not specify an address express™ with /ALL. 


Qualifiers 

/ALL 

Deactivates all watchpoints. 


Description 


WatchDoints are activated when you set them with the SET WATCH command. 
Use the DEACTIVATE WATCH command to deactivate one or more watchpoint . 

If you deactivate a watchpoint, the debugger ignores the watchpoint during 
nroffram execution. To activate a deactivated watchpoint, use the ACTIVATE 
WATCH command Activating and deactivating watchpoints enables you to run 
S"nTour program with or without watchpoints without havtng to cancel 

and then reset them. 

u ,1 thp RFRIJN command saves the current state of all static watchpoints 

to the main program unit (where execution restarts). 

Th chock if a watchpoint is deactivated, —Sh 

more information about watchpoints, see the SET WA1CH and lain or, 

commands. 

Related commands: 

CANCEL ALL 

RERUN rr,/~l TT 

(SET,SHOW,CANCEL,ACTIVATE) WATCH 


Examples 

l DBG> DEACTIVATE WATCH SDB2\T0TAL 

This command deactivates the watchpoint at variable TOTAL in module 
SUB2. 

2. DBG> DEACTIVATE WATCH/ALL 

This command deactivates all watchpoints you have set. 


CD-58 




DECLARE 




Format 


Parameters 


DECLARE p-name:p-kind [,p-name:p-kind[, 


■•]] 


p-name 


pSre a f0rma ‘ parameter (a «>at is declared within 


the command 


or°by°a Sma atThlend o/the lommandX'* ^ ^ ^ C ° nSeCUtive commas 


p-kind 


follow^ 8 the Parameter kind of a formal parameter. Valid keywords are as 


follows 
ADDRESS 


COMMAND 

VALUE 


Description 


Specifies that the actual parameter is interpreted as an address 
expression. Same effect as DEFINE/ADDRESS p-name = actual- 
parameter. 

Specifies that the actual parameter is interpreted as a command 
Same effect as DEFINE/COMMAND p-name = actual-parameter. 
Specifies that the actual parameter is interpreted as a value 

amT^ti? 011 m the current language. Same effect as DEFINE 
/VAL,UE p-name = actual-parameter. 


The DECLARE command is valid only within a command procedure. 

The MCLAMv C °™™ and binds one or more actual parameters, specified on 
^® °;™ mand lma following the execute procedure command (@), to formal 
p ameters (symbols) declared within a command procedure. 

^ p-name.p-kmcl pair specified by a DECLARE command binds one formal 
P ameter to one actual parameter. Formal parameters are bound to actual 

d P eZa« e „ns m if vr rder ? WUCh ?? ***»' P ~ ** 

command the leftmnTf^ T^ 1 formal P aram eters on a single DECLARE 
thp ^p t f th eftmost formal Parameter is bound to the first actual parameter 

* ^ s: s^:rr'„ p „“ is 

pa a raZte a Za r a d „ e ar‘ i0n a DEFINE » aviates a formal 

parameter with an address expression, a command, or a value expression in 

e curren anguage, according to the parameter kind specified The formal 

p ameters themselves are consistent with those accepted by the DEFINE 

“Z“d Z :‘T be ( deleted fr ° m the «*> witV,he DELATE 

command. For more information, see the DEFINE and DELETE commands. 
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DECLARE 


Examples 


T , a parpnT built-in symbol, which can be used only within a command 

the command procedure. 

Related commands: 

@ (Execute Procedure) 

DEFINE 

DELETE 


j i ***** Command Procedure EXAM.COM ***** 

SET OUTPUT VERIFY 
DECLARE K:ADDRESS 
EXAMINE K 

DBG> 0EXAM ARR4 FYAM 

%DEBUG-I-VERIFYIC, entering command procedure EXAM 

DECLARE K:ADDRESS 
EXAMINE K 


PROG_8\ARR4 
( 1 ) 

( 2 ) 

(3) 

(4) 


18 

1 

0 

1 


2 . 


(4)1 1 

%DEBUG-I-VERIFYIC, exiting command procedure EXAM 
DBG> 

thataddress expression. The SET OUTPUT VERIFY command causes the 
commands to echo when they are read by the debugger. 

At the debugger prompt, the @EXAM ARR4 command executes EXAM.COM, 
pas^ng the Sual parameter ARR4. Within EXAM.COM, ARR4 is 
interpreted as an address expression (an array variable, in this case). 

1 ***** Debugger Command Procedure EXAM_GO.COM 
DECLARE L:ADDRESS, M:COMMAND 
EXAMINE L; M 

DBG> @EXAM_GO X "0DUMP" 

In this example, the command procedure EXAM.CO.COM accepts two^ 
parameters, an address expression (L) and a command st g ( • 

address expression is then examined and the command is execu . 

At the debugger prompt, the @EXAM_GO X "@DUMP" command executes 
EXAM_GO.COM, passing the address expression X and the comman s ring 

@DUMP. 
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DECLARE 


3. 


****** Debugger Command Procedure VAR.DBG ***** 

SET OUTPUT VERIFY 

,DECLSRE X:V ™ e ' x > 

°Fnp E i'- - y E TA E V C ' enteri ng command procedure VAR.DBG 
JOR I - 1 TO -sPARCNT DO (DECLARE X:VALUE; EVALUATE X) 

37 

45 

%DEBUG-I-VERIFYIC, exiting command procedure VAR.DBG 

1^?" T* P ?“ d “ re VAR.DBG accepts a variable number 
parameters. That number is stored in the built-in symbol %PARCNT. 

At the debugger prompt, the @VAR.DBG command executes VAR DBG 

valuTI an?t^ a roRT eterS 12 ’ V’/f- Therefore > %PARCNT has the 
DECI ARP 1 ]l ? P !? repeated 3 timeS ‘ The F0R l0 °P causes the 
J??^ft E , t0 bmd each of the three actual Parameters (starting 

with 12) to a new declaration of X. Each actual parameter is interpreted fs 

^ptayettaTcTe 111 ““ CUn ’ mt '“S' 1886 ’ and the EVALUA ™ X command 
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DEFINE 


DEFINE 


Format 


Assigns a symbolic name to an address expression, command, or value. 

DEFINE symbol-name=parameter [,symbol-name=parameter[, ... ]] 


Parameters 


Qualifiers 


Sperifies'a'symbolic name to be assigned to an address, command, or value. The 
sJStX name can be composed of alphanumeric characters 

The debugger converts lowercase alphabetic characters to uppe . 

character must not be a number. The symbolic name must be no more than 31 
characters long. 

parameter 

Depends on the qualifier specified. 


(DefaulfiTspecifies that the defined symbol is an abbreviation for an address 
expression. In this case, parameter is an address expression. 

Sedfietthat the defined symbol is treated as a new debugger command. In this 
case, parameter is a quoted character string. This qualifier provides in simple 
cases, essentially the same capability as the following DCL command. 

$ symbol := string 

To define complex commands, you might need to use command procedures 
with formal parameters. For more information about declaring parameters to 
command procedures, see the DECLARE command. 

Specifies that the definition remain local to the command procedure in which the 
DEFINE command is issued. The defined symbol is not visible at the debugger 
command level. By default, a symbol defined within a command procedure 
visible outside that procedure. 

Specifies that the defined symbol is an abbreviation for a value. In this case, 
parameter is a language expression in the current language. 


Description 


The DEFINE/ADDRESS command enables you to assign a symbolic name to an 
address expression in your program. For example, you can define a symbol for a 
nonsymbolic program location or for a symbolic program location having a ong 
pathname prefix. Then, you can refer to that program location by the new y 
defined symbol. The /ADDRESS qualifier is the default. 
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DEFINE 


The DEFINE/COMMAND command enables you to define abbreviations for 

commfnd le^ 1 ! 1311 ? ^ ^ def f 6 nGW commands > either from the debugger 
command level or from command procedures. 88 

SHE .TT' enables y0U to assign a — to a value 

(.or me result of evaluating a language expression). 

nroce^ EFIN R^a C r AL 1 C T mand C ° nfineS Symbo1 definitions to command 
procedure^. % ’ Symb ° 1S "* gl0bal (visiWe ° Utside the ™™iand 

can first use the SET fnewdefaulfquSifier 

duration of a nltyspe * * 

In symbol translation, the debugger searches symbols you define during the 

protT g the e rb n \ S ° '{r d6fine 3 Symbd that ^already exists fn your 
’ bugger translates the symbol according to its defined definition 
unless you specify a path-name prefix. aenmtion, 

If a symbol is redefined, the previous definition is canceled, even if you used 
different qualifiers with the DEFINE command. 

Definitions created with the DEFINE/ADDRESS and DEFINE/VALUE commands 
are available only when the image in whose context they were created sTe 
current image. If you use the SET IMAGE command to establish a new current 
Twl ™ defimtlons are temporarily unavailable. However definitions created 
for allima ™ ° 0MMAND ““ DE ™ E/KEY commands are always LaTlaWe 

v^Tuetf a “ mma " d 10 "" — 

Use the DELETE command to cancel a symbol definition. 

Related commands: 


DECLARE 

DELETE 

SET IMAGE 

SHOW DEFINE 

SHOW SYMBOL/DEFINED 

Examples 

1. DBG> DEFINE CHK=MAIN\LOOP+10 

This command assigns the symbol CHK to the address MAIN\LOOP+10. 


DBG> DEFINE/VALUE COUNTER=0 

DBG> SET TRACE/SILENT R DO (DEFINE/VALOE COUNTER = COUNTER+1) 

In this example, the DEFINE/VALUE command assigns a value of 0 to 
the symbol COUNTER. The SET TRACE command cluses the debugger to 
increment the value of the symbol COUNTER by 1 whenever address R is 
encountered. In other words, this example counts the number of calls to R. 
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DEFINE 


3 . DBG> DEFINE/COMMAND BRE = "SET BREAK" 

This command assigns the symbol BEE to the debugger command SET 
BREAK. 
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DEFINE/KEY 


DEFINE/KEY 


Assigns a string to a function key. 


Note 


S~ d iS aVailabU “ the “S 0 "**"™ Motif interface to the 


Format 


Parameters 


DEFINE/KEY key-name "equivalence-string" 


key-name 

Specifies a function key to be assigned a string. Valid key names are as follows: 


Key Name 

LK201 Keyboard 

VT100-type 

VT52-type 

PF1 

PFl 

PFl 

Blue 

PF2 

PF2 

PF2 

Red 

PF3 

PF3 

PF3 

Black 

PF4 

PF4 

PF4 


KP0-KP9 

Keypad 0-9 

Keypad 0-9 

Keypad 0-9 

PERIOD 

Keypad period (.) 

Keypad period (.) 

COMMA 

Keypad comma (,) 

Keypad comma (.) 

MINUS 

Keypad minus (-) 

Keypad minus (- 

) 

ENTER 

Enter 

ENTER 

ENTER 

El 

Find 



E2 

Insert Here 



E3 

Remove 



E4 

Select 



E5 

Prev Screen 



E6 

Next Screen 



HELP 

Help 



DO 

Do 



F6-F20 

F6-F20 




You cannot define keys FI to F5 or the arrow keys (E7 to E10). 

You define keys F6 to F14 only if you have first entered the DCL 
command SET TERMINAL/NOLINE_EDITING. In that case, the line editing 
functions of the left and right arrow keys (E8 and E9) are disabled. S 
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DEFINE/KEY 


Qualifiers 


S^ n "ettring to be processed when the specified key is pressed. Typically, 
this is one or more debugger commands. If the string includes any space 
or nonalphanumeric characters (for example, a semicolon separating two 
commands), enclose the string in quotation marks ("). 


/ECHO (default) 

Controls whether the command line is displayed after the key has been pressed. 

Do not use /NOECHO with /NOTERMINATE. 

/IF_STATE=(state-name[, ... ]) 

Spedfi^oi^o^more states to which a key definition applies. The /IF_STATE 
nualifier assigns the key definition to the specified states. You can specify 
predefined states, such as DEFAULT and GOLD, 

name can be any appropriate alphanumeric string. The /NOIF.STATE qualifier 
assigns the key definition to the current state. 

/LOCK_STATE 

Co°t°b K hOT tafg'thc’stete set by /SETJ3TATE remains in effect after the 
specified key is pressed. The /LOCKJ3TATE quahfier causes fte^tetorOTiai 
in effect until it is changed explicitly (for example, with a SET KEY/blAiE 
command). The /NOLOCK_STATE qualifier causes the statoto 
only until the next terminator character is typed, or until the next de 
function key is pressed. 

/LOG (default) 

Controls whether a message is displayed indicating that the key definition has 
been successfully created. The /LOG qualifier dtsplays the message. The /NOLOG 
qualifier suppresses the message. 

/SET_STATE=state-name 

/NOSET STATE (default) , . /qFT 

Controls whether pressing the key changes the current key state. The 
STATE qualifier causes the current state to change to the specified state when 
you press the key. The /NOSET_STATE qualifier causes the current state to 

remain in effect. 

/TERMINATE 

SntTOkwhetimrthe specified string is terminated (processed) when the key is 
pressed The /TERMINATE qualifier causes the string to be terminated when t 
key is pressed. The /NOTERMINATE qualifier enables you to press other keys 
before terminating the string by pressing the Return key. 
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DEFINE/KEY 


Description 


Examples 


Keypad mode must be enabled (SET MODF KffVPi m u r 

command. Keypad mode is enabfed by Sauif y ° U *>* 

— £ 

helptopt^ the Predefined key flmcti ° ns - *» *1>® Keypad_Definitions_CI online 

On VT52- and VTlOO-series tenninals, the function keys you can use include all 

keytoard m On C LlIoi keT d°T *f minaIs and ^stations have the LK201 
y . LK201 keyboards, the function keys you can use include all of fht> 

numeric keypad keys, the nonarrow keys of the editing keypad (Find Insert Here 
and so on), and keys F6 to F20 at the top of the keyboard ’ 

A key definition remains in effect until you redefine the key enter the DFT FTF 
^EY command for that key, or exit the debugger. You can Include ley definitions 
mand procedure, such as your debugger initialization file. 

™ e Z~ STATE qualifier enables y° u to increase the number of key definitions 
available on your terminal. The same key can be assigned any number ^ 

mtions as long as each definition is associated with a different state. 

By default the current key state is the DEFAULT state. The current state can he 
changed with the SET KEY/STATE command, or by pressing a 

STATE) Change 3 ^ that WaS defined With DEFINE/ KEy/oCK_STATE/SET_ 
Related commands: 

DELETE/KEY 
(SET,SHOW) KEY 


DBG> SET KEY/STATE=GOLD 

^DEOTG-T-SETKEY, keypad state has been set to GOLD 

Stp Y/TERMINATE KP9 " SET RADIX/OVERRIDE HEX" 

•sDEBUG-I-DEFKEY, GOLD key KP9 has been defined 

key^ta^ 3 ?!^ 6 !)^^!^^^^ C ° mma f establishes GOLD as the current 
HFY ,n TheEEFINE/ KE Y command assigns the SET RADIX/OVERRIDE 
HEX command to keypad key 9 (KP9) for the current state (GOLD) The 
command is processed when you press the key. 


2 . 


DEFINE/KEY/ I F_STATE=BLUE KP9 "SET BREAK %LINE " 
•sDEBUG-I-DEFKEY, BLUE key KP9 has been defined 

zr s mSk*"'" prcss the Retum key to 
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DEFINE/KEY 


DBG> SET KEY/ STATE=DEFAULT nFFAIILT 

s-nFRilG-I-SETKEY, keypad state has been set to DEtAUL 
S DEhSy/SET SIAIE.BZD/10CKJKTE F12 - 
%DEBUG-I-DEFKEY, DEFAULT key F12 has been defined 

In this example, the SET KEY command esl« b ) ish =® ^ LK201 

rurrent state The DEFINE/KEY command makes the F12 key Con an i^ui 
state key. Pressing F12 while in the DEFAULT state cautes the 
current state to become RED. The key definition is not terminated and has 
no other effect (a null string is assigned to F12). After pressing , you 
ento-RED' commands by pressing keys that have definitions associated 

with the RED state. 
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DEFINE/PROCESS_GROUP 


DEFINE/PROCESS GROUP 


Format 


Parameters 


Assigns a symbolic name to a list of process specifications. 

value MULtSrOCESS) 8 debUgging COnfiguration (when DBG$PROCESS has the 

DEFINE/PROCESS_GROUP process-group-name =process-spec[, ... ] 


process-group-name 

Specifies a symbolic name to be assigned to a list of process specifications The 
Th^deh name Can be c , omposed of alphanumeric characters and underscores 
ch h ar«Pt bUgger r?r S Iowercase alphabetic characters to uppercase The first 

£££,■£“* a number ' The “ name must L 

process-spec 

forms? 68 ° Pr0C68S CUrren% " nder debugger “ ntrol - “y of the following 


[%PROCESS_NAME] proc-name 

[%PROCESS_NAME] "proc-name" 

%PROCESS_PID proc-id 

%PROCESS_NUMBER proc-number 
(or %PROC proc-number) 

proc-group-name 

%NEXT_PROCESS 

%PREVIOUS_PROCESS 


The process name, if that name 
contains no space or lowercase 
characters. The process name can 
include the asterisk (*) wildcard 
character. 

The process name, if that name 
contains space characters or 
lowercase characters. You can 
also use apostrophes (') instead 
of quotation marks ( "). 

The process identification number 
(PID, a hexadecimal number). 

The number assigned to a process 
when it comes under debugger 
control. Process numbers appear 
in a SHOW PROCESS display. 

A symbol defined with the DEFINE 
/PROCESS_GROUP command to 
represent a group of processes. 

Do not specify a recursive symbol 
definition. 

The process after the visible process 
in the debugger’s circular process 
list. 

The process previous to the visible 
process in the debugger’s circular 
process list. 
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DEFINE/PROCESS_GROUP 


Description 


Examples 


%VISIBLE_PROCESS 


The process whose call stack, register 
set, and images are the current 
context for looking up symbols, 
register values, routine calls, 
breakpoints, and so on. 


If you do not specify a process, the symbolic name is created but contains no 
process entries. 


The DEFINE/PROCESS_GROUP command assigns a symbol to list °f process 
Specifications. You can then use the symbol in any command where a hst of 
process specifications is allowed. 

The DEFINE/PROCESS_GROUP command does not verify the existence of a 
Specified process. This enables you to specify processes that do not yet exist. 

To identify a symbol that was defined with the DEFINE/PROCESS_GROUP 
commandf use the SHOW SYMBOL/DEFINED command. To delete a symbolthat 
w 7d£d with the DEFINE/PROCESS.GROUP command, use the DELETE 

command. 

Related commands: 

DELETE 

(SET,SHOW) DEFINE 
SHOW SYMBOL/DEFINED 


Current PC 
FS_PROG\%LINE 37 
NET PROGULINE 24 


1. DBG 1> DEFINE/PROCESS_GROUP SERVERS =FILE_SERVER,NETWORK_SERVER 
DBG~1> SHOW PROCESS SERVERS 
Number Name Hold State 

* 1 FILE_SERVER step 

2 NETWORK_SERVER break 

DBG_1> 

This DEFINE/PROCESS.GBOUP commandI assigns 

SERVERS to the process group consisting of FILE_SERV 

SERVER. The SHOW PROCESS SERVERS command displays information 

about the processes that make up the group SERVERS. 

2 USER 3> DEFINE/PROCESS_GROUP G1=%PR0CESS_NUMBER 1,%VISIBLE_PROCESS 
USER“3> SHOW SYMBOL/DEFINED G1 

defi bound to: "%PROCESS_NUMBER 1, %VISIBLE_PROCESS" 
was defined /process_group 
USER_3> DELETE G1 

This DEFINE/PROCESS_GROUP command assigns the symbolic name G1 to 
the process group consisting of process 1 and the visible P™ 0 ^ (P™cess 3) 
The SHOW SYMBOL/DEFINED G1 command identifies the defin^janhd 
Gl. The DELETE G1 command deletes the symbol from the DEFIN y 

table. 
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DEFINE/PROCESSGROUP 


3. 


DBG_2> DEFINE/PROCESS GROUP A = B C D 
DBG_2> DEFINE/PROCESS GROUP B = eVg 
DBG_2> DEFINE/PROCESS GROUP E = iVa 


This series of DEFINE/PROCESS_GROUP 
invalid uses of the command. 


commands illustrate valid and 
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DELETE 



DELETE 


Deletes a symbol definition that was 


established with the DEFINE command. 


Format 

DELETE [symbol-name[, ... ]] 


Parameters 


Qualifiers 


SpedfiesTaT^nbol whose definition is to be deleted from the DEfTOE e^sbol 
tebte Do noYuse the asterisk (*) wildcard character Instead use the /ALL 
Qualifier. Do not Bpecify a symbol name with /ALL. If you use the /LOCAL 
Qualifier the symbol specified must have been previously defined with 
SbS«S command. If you do not specify /LOCAL, the symbol specified 
must have been previously defined with the DEFINE command without /LOCAL. 


Metes all global DEFINE definitions. Using /ALL/LOCAL deletes all teal 
DEFINE definitions associated with the current command proce ure u 
global DEFINE definitions). 

D°etes\he (local) definition of the specified symbol from tiiteurren^w^^mid 
procedure. The symbol must have been previously defined with the DE*i 
/LOCAL command. 


Description 


he DELETE command deletes either a g obal DEFINE sjmbd or a bcal 
iFFINE svmbol A global DEFINE symbol is defined with the DEFINE command 
E J. n OCAL aua iifier. A local DEFINE symbol is defined in a debugger 
ommand procedure with the DEFINE/LOCAL command, so that its definition is 
onfined to that command procedure. 


Related commands: 

DECLARE 

DEFINE 

SHOW DEFINE 

SHOW SYMBOL/DEFINED 


Examples 


i. 


DBG> DEFINE X = INARR, Y = OUTARR 
DBG> DELETE X,Y 


this example, the DEFINE command defines XaDdYw gal.*5^ 
•responding to INARR and OUTARR, respectively. The DELETE command 
letes these two symbol definitions from the global symbol table. 
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DELETE 


DBG> DELETE/ALL/LOCAL 

^taT a “ d del6teS a " l0Ca ‘ Symb01 defl ” Wons ‘h= current command 
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DELETE/KEY 


DELETE/KEY 

Deletes a key definition that was established with the DEFINE/KEY command or, 


by default, by the debugger. 


Note 


is command is not available in the DECwindows Motif interface to the 


This 
debugger. 


Format 


DELETE/KEY [key-name] 


Parameters 


Snecifies^ key whose definition is to be deleted. Do not use the asterisk (*) 
wdhicard character. Instead, use the /ALL qualifier. Do not specrfy a key name 
with /ALL. Valid key names are as follows: 


Key Name 

LK201 Keyboard 

VT100-type 

VT52-type 

PF1 

PF1 

PF1 

Blue 

PF2 

PF2 

PF2 

Red 

PF3 

PF3 

PF3 

Black 

PF4 

PF4 

PF4 


KP0-KP9 

Keypad 0-9 

Keypad 0-9 

Keypad 0-9 

PERIOD 

Keypad period (.) 

Keypad period (.) 

COMMA 

Keypad comma (,) 

Keypad comma (,) 

MINUS 

Keypad minus (-) 

Keypad minus (- 

-) 

ENTER 

Enter 

ENTER 

ENTER 

El 

Find 



E2 

Insert Here 



E3 

Remove 



E4 

Select 



E5 

Prev Screen 



E6 

Next Screen 



HELP 

Help 



DO 

Do 



F6-F20 

F6-F20 




Qualifiers 


/STATE =state-name. 
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DELETE/KEY 


Description 


Examples 


/LOG (default) 

/NOLOG 

definitions hav^be^deleted ^The^LOG md , 1C fi atm r g !; hat the specified key 
the message. The /NOLOG^^ “"*> ^ 

/STATE=(state-name 
/NOSTATE (default) 

key def^ The ^OSmTEqua iffiefdlTe^he 

diange^wit^ th^SET^KEY/STATE erf The CUITCnt state can be 

STATEX 11311 ^ ^ ^ that WaS defined 


The DELETE/KEY command is like the DCL command DELETE/KEY. 

Keypad mode must be enabled (SET MODE KFVPAm w _ 

command. Keypad mode is enabled by def^lf ^ “ Se tlUS 

Related commands: 

DEFINE/KEY 
(SET,SHOW) KEY 


DBG> DELETE/KEY KP4 

%DEBUG-I-DELKEY, DEFAULT key KP4 has been deleted 

SET KF m YT d ‘“ft definition for KP4 in the state last set by the 

SET KEY command (by default, this is the DEFAULT state). 

DBG> DELETE/KEY/STATE=(BLUE,RED) COMMA 

^^ r U ^" I-DELKEY ' BL0E fc ey COMMA has been deleted 
«DEBUG-I-DELKEY, RED key COMMA has been deleted 

Ind S RED“ a a n tes deleteS ‘ he k6y definiti ° n f ° r the °° MMA key in the BLUE 


CD-75 




DEPOSIT 


DEPOSIT 


Format 


Changes the value of a program variable. More generally, deposits a new value at 
the location denoted by an address expression. 


DEPOSIT address-expression = language-expression 


Parameters 


an address expression can also be a memory address or a register and ca 
composed of numbers (offsets) and symbols, as well as one or more opera , 
operands or delimiters. For information about the debugger symbols for the 
Asters ’and about the operators you can use in address expressmns, see the 
Built_in_Symbols and Address_Expressions help topics. 

You cannot specify an entire aggregate variable (a composite data ^ u ^ r ® SUch 
as an array or a record). To specify an individual array element or a reco 
component, follow the syntax of the current language. 

SeT^vTeto be deposited. You can specify any language expression tiiat 
f« v« Vd in the current language. For most languages, the expression can include 
L tles Z7e <non.Sn£>site, single-valued) variables but not the names 
If legate variables (such as arrays or records). If the expression contams 
symbols with different compiler-generated types, the debugger uses e ru 
the current language to evaluate the expression. 

Tf the expression is an ASCII string or an assembly-language instruction, you 
must enclose it in quotation marks ( " ) or apostrophes ('). If the string contains 
q^iotationmarks or apostrophes, use the other delimiter to enclose the stnng. 

If the string has more characters (1-byte ASCII) than can fit into the program 

the remaining characters to the right of the string by inserting ASCII space 
characters. 


Qualifiers 


this qualifier as /AC. 

Deposits an ASCII string into the address given by a 

at the specified location. You must specify a string on the right-hand side of 
equal sign. The specified location must contain a stnng descnptor. If the st g 
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DEPOSIT 


Alpha 


/ASCII :n 

r ifya 

~re p a^ 

/ASCIW 

Deposits a counted ASCII string into the specified location. You must specify a 
b ,™2 ng ?t h ui S * de . of tbe e< I ual Sl 8" The deposited string is preceded 

this quaMerT/AW ““ ^ ° f the 8tri "* Y °“ «“ ^ specify 

/ASCIZ 

'ZSr&zzte that “ **- 

/BYTE 

Deposits a 1-byte integer into the specified location. 

/D_FLOAT 

Converts the expression on the right-hand side of the equal sign to the D floating 
type (length 8 bytes) and deposits the result into the specified location. § 

/DATE_TIME 

2^1^ reP f Sen , ti c ng 3 datC and time (for exam P le ’ 21-DEC-1988 
a n+'h q u \ mterna ^ f° rma t for date and time and deposits that value 

ft”&llowlS e foS: the SP6Cified l0Cati0 ”' SP6dfy “ abSOlUte date and ,ime “ 

[dd-mmm-yyyy[ ; ]] [hh:mm:ss.cc] 

/EXTENDED_FLOAT 

Sm^to’the'tEERT<i Z nVe T the , “ r ’™ sslon on the right-hand side of the equal 
spTcifled locatfen ; 8 *”* ^ ^ “ d de P° site "»"» ^ «*> 

/FLOAT 


Sn'TtheTS' the fP™ 88 * 0 ” the right-hand side of the equal 

T <eneth 4 bytes) and dep08ite the resa,t into *• 
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DEPOSIT 


Alpha 






Alpha 


Alpha 


On Alpha processors, converts the expression on the right-hand side of the equal 
sign to the IEEE T_floating double-precision (length 8 bytes) and eposi 
result into the specified location. ♦ 

Convertethe expression on the right-hand side of the equal sign to the GJloating 
type (length 8 bytes) and deposits the result into the specified location. 

/H_FLOAT 

On VAX nrocessors converts the expression on the right-hand side of the equal 
type (length 16 bytes) and deposits the result mto the 

specified location. ♦ 

/INSTRUCTION 

On VAX processors, deposits an instruction into the specified location. The 
S.Sn on the righ "hand side of the equal sign must be a stnng representmg 
an assembly-language instruction. ♦ 

/LONG_FLOAT 

On Alpha processors, converts the expression on the right-hand side oftheequa 1 
sign to the IEEE S_floating type (single precision, length 4 bytes) and depos 
the result into the specified location. ♦ 

/LONG_LONG_FLOAT 

On Alpha processors, converts the expression on the right-hand side of the equal 
sign to the P IEEE T.floating type (double-precision, length 8 bytes) and deposits 
the result into the specified location. ♦ 

De°pofite a'longword integer (length 4 bytes) into the specified location. 

Deplsfis^octaword integer (length 16 bytes) into the specified location. 

Convert s^ the expression on the right-hand side of the equal sign to a packed 
decimal representation and deposits the resulting value into the specified 
location. The value of n is the number of decimal digits. Each digit occupies o 

nibble (4 bits). 

Depute a quadword integer (length 8 bytes) into the specified location. 

IS FLOAT 
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Examining and Manipulating Program Data 
8.3 Examining and Depositing Instructions 


module TEST 
1 
2 

3 

4 

5 

6 

7 

8 
9 

10 
11 
12 

13 

14 

15 


.TITLE 

TEST 

TEST$START:: 

.WORD 

0 

MOVL 

#2,R2 

BRB 

LABEL 2 

.LONG 

A X12345 

.LONG 

A X14465 

LABEL 2: 

MOVL 

#5,R5 

.END 

TEST$START 


The following EXAMINE command displays the instruction at the start of line 6: 

S A #02,R2 


MOVL 


DBG> EXAMINE %LINE 6 
TEST\TEST$START\%LINE 6 
DBG> 

The following EXAMINE command correctly interprets and displays the logical 
successor entity as an instruction at line 7: 

DBG> EXAMINE [Tteu^J 

TEST\TEST$START\%LINE 7: BRB TEST\TEST$START\LABEL 2 
DBG> — 

However, the following three EXAMINE commands incorrectly interpret the three 
logical successors as instructions: 

DBG> EXAMINE [Rm^ 

7t2: “ LF3 S A #11 .00000, S A #0.5625000, S A f 0.5000000 

IEST\TeSS«S j"f r “““; U “:„ ine O al or “"defined addressing modes 
roG> X SlNE' ft pS^ INE 7 6: 1101,03 S #°.5625000 [R4],.5000000, @W A 5505 (R0) 

TEST$START+12: HALT 

DBG> 

8.3.2 Depositing Instructions (VAX Only) 

f? n YY* P rocessor s, you can deposit instructions as well as examine them. Use 
the following DEPOSIT command syntax: 

DEPOSIT/INSTRUCTION address-expression = "instruction” 

You must enclose the instruction in either quotation marks or apostrophes. You 
must also use the /INSTRUCTION qualifier with the DEPOSIT command, which 
indicates that the delimited string is an instruction and not an ASCII string. 

deposit several instructions, you can first enter the SET TYPE 
/OVERRIDE INSTRUCTION command (see Section 8.5.2). You then do not need 
to use the /INSTRUCTION qualifier on the DEPOSIT command. 

Instructions occupy different numbers of bytes depending on their operands 
When depositing instructions of arbitrary lengths into successive memory 
locations, use the logical successor operator (Return key) to establish the next 
unoccupied location where an instruction can be deposited. The following example 
shows the technique: p 
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Examining and Manipulating Program Data 
8.3 Examining and Depositing Instructions 


DRr> SET TYPE/OVERRIDE/INST ! Set the default type to instruction. 

DBG> DEPOSIT 730 = "MOVB #77, Rl"! Deposit an instruction^beginning^at address^ 

DBG> EXAMINE . 

730: MOVB #77,Rl 


dbg> examine mg 

734: HALT 

DBG> DEPOSIT . = "MOVB #66, R2" 
DBG> EXAMINE . 

734: MOVB #66,R2 
DBG> 


: UCWOlL a. 11 - -J — u 

! Examine the current entity to verify the deposit, 
j M a ke the logical successor the new current entity. 


! Deposit the next instruction. 

! Display and verify the deposit. 


When you replace an instruction, be sure that the new instruction, including 
operands, is the same length in bytes as the old instruction. If the new 
instruction is longer, you cannot deposit it without overwriting, which will destroy 
the next instruction. If the new instruction occupies fewer bytes of memory 
than the old one, you must deposit NOP instructions (instructions that cause 
no operation) in bytes of memory left unoccupied after the replacement. The 
debugger does not warn you if an instruction you are depositing will overwrite a 
subsequent instruction, nor does it remind you to fill in vacant bytes of memory 
with NOPs. 

The following example shows how to replace an instruction with an instruction of 
equal length: 


DBG> SET STEP INSTRUCTION ! Step by instruction. 

DBG> STEP 

stepped to 1584: PUSHAL (Rll) 

DBG> STEP , , . , 

stepped to 1586: CALLS #1,L A 2224 ! Instruction to be replaced. 


DBG> EXAMINE .%PC 
1586: CALLS #1,L A 2224 
DBG> EXAMINE I Return | 

1593: CALLS #0,L A 2216 

DBG> DEPOSIT/INST 1586 = "CALLS 

DBG> EXAMINE . 

1586: CALLS #2,L A 2224 

DBG> EXAMINE I Return | 

1593: CALLS #0,L A 2216 

DBG> ♦ 


! Determine start of next 
! instruction (1593). 
#2,L A 2224" 

! Deposit new instruction. 

! Verify that instruction 
! is deposited. 

! Verify that the next 
! instruction is unchanged. 


8.4 


Examining and Depositing into Registers 

^ The VAX architecture provides 16 general registers and 18 vector registers, some 

^ of which are used for temporary address and data storage. Table 8-1 identifies 

the debugger built-in symbols that refer to VAX registers. 


Table 8-1 Debugger Symbols for VAX Registers 

Symbol Description _ 

VAX General Registers 


%R0 . . . %RH 
%AP (%R12) 
%FP (%R13) 
%SP (%R14) 


General-purpose registers (RO . . . Rll) 
Argument pointer (AP) 

Frame pointer (FP) 

Stack pointer (SP) 


(continued on next page) 
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DEPOSIT 


Alpha 


Same as /LONG_FLOAT. ♦ 

/TASK 

a task ralue <a “ sk " or 

be a valid task valle SP<!Clfied locat, ° n - The de I*> sited ™lue must 

/T_FLOAT 


Alpha 


Same as /LONG_LONG_FLOAT. ♦ 

/TYPE=(name) 

s=a C=.“as=. sxszrisF 

/X_FLOAT 


Alpha 


Description 


Same as /EXTENDED_FLOAT. ♦ 

/WORD 

Deposits a word integer (length 2 bytes) into the specified location. 


W C£m USe the , DE ^° SIT command t0 ch »nge the contents of any memory 
location or register that is accessible in your program. For high-level languages 

£ d -- * ha ™ ,aa » f a 

ForTda a„°d P " ° ther loCati ° n SpedR<!d to thefeft of the 4ua ‘£ 

For Ada and Pascal, you can use -:=■ instead of in the command syntax 

Ildri e . bUgSer recogn * 2es ‘ he compiler-generated types associated with symbolic 
ddress expressions (symbolic names declared in your program) Symbolic 

address expressions include the following entities: y 

Variable names. When specifying a variable with the DEPOSIT command 
use the same syntax that is used in the source code. command, 

Routine names, labels, and line numbers. On VAX systems these are 
associated with instructions. You can deposit instructions using basically 
e same techniques as when depositing into string variables However 
^® ust also use the /INSTRUCTION qualifier or first enter a SFT TYPF 
NSTRUCTION or SET TYPE/OVERRIDE INSTRUCTION command 

J5KSL2S y °“ ^ a DEP0SIT • *• ‘ak- the 

’ “eW a aT^rl e itaUon. 6 ^ 0 ” 40 ““ ‘ eft » f *> 
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DEPOSIT 


Tf tv,A nrnPTam location has a symbolic name, the debugger associates the 
Latin She s^b„r s compfier-generated type. If the location does not 
have a symbolic name (and, therefore, no associated compiler-generated 
t V ne) th/debugger associates the location with the type longword mtege y 
dSauklMs means that, by default, you can deposit integer values that do 
not exceed 4 bytes into these locations. 

. It evaluates the language expression specified to the right 

in the syntax of the current language and in the current radi , y 

value. The current language is the language last estabhshed 

T ANGIJAGE command. By default, if you did not enter a SE 

theT^nt language is the language of the module contammg the 

main program. 

. Tt checks that the value and type of the language expression is consistent 
^h the type of the address expression. If you try to deposit a value that 
is incompatible with the type of the address expression the debugger issue 
a diagnostic message. If the value is compatible, the debugger deposits 
value into the location denoted by the address expression. 

The debueeer might do type conversion during a deposit operation if the language 
^les ahow tt For example, a real value specified to the right of the equal sign 
St be Inverted to an integer value if it is being deposited into a location with 
antteger type. In general, the debugger tries to follow the assignment mles for 

the current language. 

There are several ways of changing the type associated with a program location 
so that you can deposit data of a different type into that location. 

. To change the default type for all locations that do not have a symbolic name, 
you can specify a new type with the SET TYPE command. 

. To change the default type for all locations (both thosethatdoanddo^not 
have a symbolic name), you can specify a new type with the SET TYP 
/OVERRIDE command. 

. To override the type currently associated with a particular location for the 
duration of a single DEPOSIT command, you can specify a new type by u g 
a qualifier (/ASCII:n, /BYTE, /TYPE =(name), and so on). 

When debugging a C program, or a program in any case-specific language, you 
Innot use the DEPOSIT/TYPE command if the type specified is a mixed or 
lowercase name. For example, suppose the program has a function like the 

following: 

xyzzy_type foo () 

{ 

xyzzy_type z; 
z = get_z (); 
return (z); 

If you try to enter the following command, the debugger issues a message that it 
cannot find the type “xyzzy_type”: 

DBG> DEPOSIT/TYPE=(xyzzy_type) z="whatever" 

The debugger can interpret and display integer data in any one »f four radixes: 
STSal, hexadecimal, and octal. The default radnc for both data entry 
and display is decimal for most languages. 
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DEPOSIT 




Alpha 


Examples 


SSlSr “ BLISS - which have a 

“A® 0 - 32 - - MACRO-64, 
SdluTra" ^ SET ^OVERRIDE _de to change 

The DEPOSIT command sets the current entity built-in symbols %CTTPT OP 

(%NEXTLOC) are based on the value of the « Sl,CCeSS ° rS 

Related commands: 

CANCEL TYPE/OVERRIDE 

EVALUATE 

EXAMINE 

MONITOR 

(SET,SHOW,CANCEL) RADIX 
(SET,SHOW) TYPE 


1. DBG> DEPOSIT 1 = 7 

This command deposits the value 7 into the integer variable I. 

2. DBG> DEPOSIT WIDTH = CURRENTJJIDTH + 24.80 

de , P ° SltS !? e value of the expression CURRENT WIDTH + 
24.80 into the real variable WIDTH. - 

3. DBG> DEPOSIT STATUS = FALSE 

This command deposits the value FALSE into the Boolean variable STATUS. 

4. DBG> DEPOSIT PART_NUMBER = "WG-7619.3-84” 

M^NTOBER eP ° SitS the S ‘ ring W °- 7619 ^ into the variable 


5. DBG> DEPOSIT EMPLOYEE.ZIPCODE = 02172 

™ S p“ d6P0Site the Va!ue 02172 int ” component ZIPCODE of record 


DBG> DEPOSIT ARR(8) = 35 
DBG> DEPOSIT A = 14 


In this example, the first DEPOSIT command deposits the value 35 into 
8 ofarray AKR- A s a result, element 8 becomes the current entity. 

element nZT U ^ pred ~ “ f ' 


DBG> FOR I = 1 TO 4 DO (DEPOSIT ARR(I) = 0) 

This command deposits the value 0 into elements 1 to 4 of array ARR. 
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8 %DEBUG-E-OPTNOTALLOW,'operator "DEPOSIT" not allowed on 
given data type 

The debugger alerts you when you try to deposit data of the wrong type 
££ avariable (in this case, if you try to deposit an integer.value, mto an 
enumerated type variable). The E (error) message severity indicates that 
debugger does not make the assignment. 

9 DBG> DEPOSIT VOLUME = - 100 , 

%DEBUG-I-IVALOUTBNDS, value assigned is out of bounds 

at or near 

The debugger alerts you when you try to deposit an out-of-bounds value into 
I variaWe g (L this case a negative value). The I (informationa ) message 
severity indicates that the debugger does make the assignment. 


10 DBG> DEPOSIT/BYTE WORK = %HEX 21 

This command deposits the expression %HEX 21 into location WORK and 
converts it to a byte integer. 

11 DBG> DEPOSIT/OCTAWORD BIGINT = 111222333444555 

This command deposits the expression 111222333444555 into location 
BIGINT and converts it to an octaword integer. 


12 DBG> DEPOSIT/FLOAT BIGFLT - 1.11949*10**35 

This command converts 1.11949*10**35 to an FJloating type value and 
deposits it into location BIGFLT. 

13. DBG> DEPOSIT/ASCII:10 WORK+20 = 'abcdefghij' 

This command deposits the string "abcdefghij-' into the location that is 20 
bytes beyond that denoted by the symbol WORK. 

14. DBG> DEPOSIT/INSTR SUB2+2 = 'MOVL #20A,R0' 

On VAX systems, this command deposits the instruction MOVL #20A,R0’ into 
the location SUB2 + 2 bytes. 


15 . 


DBG> DEPOSIT/TASK VAR = %TASK 2 
DBG> EXAMINE/HEX VAR 
SAMPLE.VAR: 0016A040 
DBG> EXAMINE/TASK VAR 


iMPLE.VAR: I TASK 2 

he DEPOSIT command deposits the Ada task value %TASK 2 

AR The subsequent EXAMINE commands display the contents of VAR m 

exadecimal format and as a task value, respectively. 





DISABLE AST 


Format 


Description 


Disables the delivery of asynchronous system traps (ASTs) in your program. 


DISABLE AST 


The ENABLE AST command reenables the delivery of A^To in^i a- 
pending ASTs (ASTs waiting to be deleted) ' 8 ^ 


Note 


Any can by your program to the $SETAST system service that enables 
ASTs overrides a previous DISABLE AST command. 


Example 


Related commands: (ENABLE,SHOW) AST. 


DBG> DISABLE AST 
DBG> SHOW AST 
ASTs are disabled 
DBG> 


“«“efb“f S H c ™ d rrnd the deiive,y ° f ASTS in 


as 


CD-83 








DISCONNECT 



DISCONNECT 


WolA -„ q . orocess from debugger control without terminating the process This 

command applies equally to a default or muitiprocess debugging configura ion 

(that is, when DBG$PROCESS is either undefined or has the value imv 
MULTIPROCESS). 


Format 


Parameters 


DISCONNECT process-spec 

currently under debugger control. Use any of the following 


forms: 

[%PROCESS_NAME] proc-name 

[%PROCESS_NAME] "proc-name" 

%PROCESS_PID proc-id 

%PROCESS_NUMBER proc-number 
(or %PROC proc-number) 

proc-group-name 

%NEXT_PROCESS 

%PREVIOUS_PROCESS 

%VISIBLE_PROCESS 


The OpenVMS process name, if that 
name contains no space or lowercase 
characters. The process name can 
include the asterisk (*) wildcard 
character. 

The OpenVMS process name, if that 
name contains space or lowercase 
characters. You can also use 
apostrophes (') instead of quotation 
marks ("). 

The OpenVMS process identification 
number (PID, a hexadecimal 
number). 

The number assigned to a process 
when it comes under debugger 
control. Process numbers appear 
in a SHOW PROCESS display. 

A symbol defined with the DEFINE 
/PROCESS_GROUP command to 
represent a group of processes. 

Do not specify a recursive symbol 
definition. 

The process after the visible process 
in the debugger’s circular process 
list. 

The process previous to the visible 
process in the debugger’s circular 
process list. 

The process whose call stack, register 
set, and images are the current 
context for looking up symbols, 
register values, routine calls, 
breakpoints, and so on. 
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DISCONNECT 


Description 


tS* s sr f T de T er “ n “ 

specify a process with the EXIT or QWTrommand (In COn * rast ’ when y° u 

^ U11 command » the process is terminated ) 

SSSwSSSSiSw 

$ RUN/DEBUG image_name 

DBG> DISCONNECT image_name_process 

DISCONNECT'cm^ndTsh^Twow^ debUgBer a " d isSue the 

$ DEBUG/KEEP 

DBG> DISCONNECT image name 


Caution 


The debugger kernel runs in the same process as the image being 
debugged. If you issue the DISCONNECT command for this process you 
release your process, but the kernel remains activated. 

This activation continues until the program image finishes running. 

If you install a new version of the debugger while one or morP 
disconnected but activated kernels inhabit user program space you 
can experience problems with debugger installation and behavior 


Example 


Related commands: 

EXIT 

QUIT 

CONNECT 


DBG> DISCONNECT JONES 


”min“e p': a c::i Pr “ eSS J0NES daba ^ without 
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display 


display 


Creates a new screen 


display or modifies an existing display. 


Note 


is command is not available in the DECwindows Motif interface to the 


This 
debugger. 


Format 


DISPLAY display-name [AT window-spec] [display-kind] [,■■•] 


Parameters 


display-name 

Specifies the display to be created or modified. 

If you are creating a new display, specify a name that is not already used as a 
display name. 

If you are modifying an existing display, you can specify any of the following 
entities: 

• A predefined display: 

SRC 

OUT 

PROMPT 

INST 

REG (VAX only) 

. A display previously created with the DISPLAY command 

• A display built-in symbol: 

%CURDISP 

%CURSCROLL 

%NEXTDISP 

%NEXTINST 

%NEXTOUTPUT 

%NEXTSCROLL 

%NEXTSOURCE 

You must specify a display unless you use /GENERATE (parameter optional), or 
/REFRESH (parameter not allowed). 

You can specif, more than one display, each with an optional window specification 
and display kind. 

C™s S thTscreen window at which the display is to be positioned. You can 
specify any of the following entities: 

• A predefined window. For example, RH1 (right top half). 

. A window definition previously established with the SET WINDOW command. 
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DISPLAY 


on the Mt i 

L y ^SglT^^?spSy°ra*ewXXT iti0n d<>P<!ndS °" Whether >' ou 

‘ Jha^T SPeCifying “ “ iSting disphy ’ the P^ion of the display is not 

display-kind 

Specifies the display kind. Valid keywords are as follows: 

DO (commandl • • . ]) Specifies an automatically updated output 

display. The commands are executed in the 
order listed each time the debugger gains 
control. Their output forms the contents of 
the display. If you specify more than one 
command, the commands must be separated by 
semicolons. J 

Specifies an instruction display. If selected 
as the current instruction display with 
the SELECT/INSTRUCTION command, it 

S the out P ut fr° m subsequent EXAMINE 
/INSTRUCTION commands. 

Specifies an automatically updated instruction 

SSXJ?® command specified must be an 
EXAMINE/INSTRUCTION command. The 
instruction display is updated each time the 
debugger gains control. 

Specifies an output display. If selected as 
the current output display with the SELECT 
/OUTPUT command, it displays any debugger 
output that is not directed to another display. 

SeTeCTANPTTT CUrrent l npUt display with the 
SELECT/INPUT command, it echoes debugger 

input. If selected as the current error display 

with the SELECT/ERROR command, it displays 

debugger diagnostic messages. 

Specifies an automatically updated register 
display. The display is updated each time the 
debugger gains control. 

Specifies a source display. If selected as the 
current source display with the SELECT 
/SOURCE command, it displays the output 
from subsequent TYPE or EXAMINE/SOURCE 
commands. 


INSTRUCTION 


INSTRUCTION ( command) 


OUTPUT 


t REGISTER 


SOURCE 
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DISPLAY 


Qualifiers 


SOURCE {command) 


Specifies an automatically updated source 
display. The command specified must be a 
TYPE or EXAMINE/SOURCE command. 
The source display is updated each time the 
debugger gains control. 


You cannot change the display kind of the PROMPT display. 

If you omit the display-kind parameter, the display kind depends on whether you 
are specifying an existing display or a new disp ay. 

. If you are specifying an existing display, the display kind is not changed. 

. If you are specifying a new display, an OUTPUT display is created. 


Erasefthe entire contents of a specified display. Do not use this qualifier with 
/GENERATE or when creating a new display. 

/DYNAMIC (default) 

command. By default (/DYNAMIC), all user-defined and predefined disp ays 
adjust their dimensions automatically. 

Regenerates the contents of a specified display. Only automatically generated 

i-srs,*isavasifessr -■<- 

same region of the screen. You cannot hide the PROMPT display. 

/MARK_CHANGE 

/tv/tatjit pitaN(TF anv lines in which some contents have change 
updated display to be highlighted when they change. 

The /NOMARK CHANGE qualifier (default) specifies that any hnes that change 
I DoTplays'are not to be marked. This qualifier cancels the effect of a 
previous /MARKCHANGE on the specified display. 
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DISPLAY 


/POP (default) 

/NOPOP 

“^OTTOHX Ual “ ier Prese " es 1116 ° rder 0f a11 dis P'^ on the pasteboard (same 

/PROCESS[=(process-spec)l 
/NOPROCESS (default) 

(when DB WROCESS has 

ssrSr? saacitssssii=1, 

sSJsssZi 1 yZzzt? disp j ay r “ d and m »“ 

PROMPT display. ’ k any dlsp ay P rocess specific, except the 

Is h S L^teT^th^lf p TOCeSS: fi P r ) quaIifier causes the specified display to be 

anv of thp fnli • specified Process. You must include the parentheses Use 
any ot the following process-spec forms: s ' use 


[%PROCESS_NAME] proc-name 

[%PROCESS_NAME] - proc-name » 

%PROCESS_PID proc-id 

%PROCESS_NUMBER proc-number 
(or %PROC proc-number) 

proc-group-name 

%NEXT_PROCESS 


The process name, if that name 
contains no space or lowercase 
characters. The process name can 
include the asterisk (*) wildcard 
character. 

The process name, if that name 
contains space or lowercase 
characters. You can also use 
apostrophes (') instead of quotation 
marks ( n ). 

The process identification number 
(PID, a hexadecimal number). 

The number assigned to a process 
when it comes under debugger 
control. Process numbers appear 
in a SHOW PROCESS display. 

A symbol defined with the DEFINE 
/PROCESS_GROUP command to 
represent a group of processes. 

Do not specify a recursive symbol 
definition. 

The process after the visible process 
in the debugger’s circular process 
list. 
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%PREVIOUS_PROCESS 

process list. 

tttot'qt W PPOPFqs The process whose call stack, register 

%VISIBLE_PROCESS get> and images are the current 

context for looking up symbols, 
register values, routine calls, 
breakpoints, and so on. 

™ ™ nPIf oo oualifier causes the specified display to be associated with the 
The /PROCEoo quauner caus v mqpT AY/PROCESS command was 

process that was the visible process when the DISPLAY/rKU^ 

executed. 

/MnPPOPFSS Qualifier (which is the default) causes the specified display 
“sk process, which might change during program 

execution. . . f 

If you do not specify /PROCESS, the current process-specific behavior (i any) o 
the specified display remains unchanged. 

For more information, see the /SUFFIX qualifier. 

/PUSH 

ThefpUSH qualifier has the same effect as /HIDE,The /NOPUSHqualifier 
preserves the order of all displays on the pasteboard (same as /NOPOP). 

Etathe terminal screen. Do not specify any command parameters with this 
qualifier. You can also use Ctrl/W to refresh the screen. 

'Safe display as being removed from the display pasteboard 

and its contents are preserved. You cannot remove the PROMPT display. 

qualifier, the maximum size of the display is as follows: 

. If you specify an existing display, the maximum size is unchanged. 

. If you are creating a display, the default size is 64 lines. 

For an output or DO ^pfjfa^gourccfor inskck^display'rfgives'the 6 

nl"u SntmLes of 

£ EESTS& rouanef whose instructions are displayed (instructions are 
decoded from the image as needed). 




DISPLAY 


/SUFFIX[=process-identifier-type] 

fte^alulTlV^^ 

name. Use S®* a dis ^ 

the visible process at the SS^* w t£T' ^ 

Use any of the following process-identifier-type keywords: 


PROCESS_NAME 
PROCESS_NUMBER 

PROCESS_PID 


The display-name suffix is the process name. 

“a 6 SHOW PROCES^display) Pr0CeSS nUmb6r <“ ^ 
number P (PID) ame SUffiX “ the process ““Motion 


SSSasSSaSKF* tTt 

the /[NOJPROCESS qualifier. T/SUFFIX command). See also 


Description 


Examples 


You can use the DISPLAY command to create a display or to modify an existing 

Related commands: 

Ctrl/W 

EXPAND 

MOVE 

SET PROMPT 
(SET,SHOW) TERMINAL 
(SET,SHOW,CANCEL) WINDOW 
SELECT 

(SHOW,CANCEL) DISPLAY 


1. DBG> DISPLAY REG 

rttSStiST 1 shows the predeflned register displa * m». 
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2 DBG> DISPLAY/PUSH INST 

This command pushes display INST to the bottom of the display pasteboard, 
behind all other displays. 

3 . DBG> DISPLAY NEWDISP AT RT2 
DBG> SELECT/INPUT NEWDISP 

, . i nmPT ,AY command shows the user-defined display 

^ISP^e"^e Ld of the s^een. Tire SELECT/INPUT 

command selects NEWDISP as the current input display. NEW 
echoes debugger input. 

4 DBG> DISPLAY DISP2 AT RS45 
DBG> SELECT/OUTPUT DISP2 

to this example, the DISPLAY command creates a d'Splay namcd WSPJ 
essentially at the right bottom half of the screen, above the PROMT toplay, 
wMch is located at S6. This is an output display by default. The SELECT 
/OUTPUT command then selects DISP2 as the current output display. 

s DBG> SET WINDOW TOP AT (1,8,45,30) 

dbg> display newinst at top instruction 

DBG> SELECT/INST NEWINST 

. , a .L.Q ctt WINDOW command creates a window named TOP 

extending down for 8 lines and to the 
• frfr so columns The DISPLAY command creates an instruction display 
NEWNST m belayed through TOP. The SELECT/INST command 
selects NEWINST as the current instruction display. 

6 . DBG> DISPLAY CALLS AT Q3 DO (SHOW CALLS) 

This command creates a DO display named 
the debugger gains control from the program, 

is executed and the output is displayed m display CALLS, repla g y 
previous contents. 

7 DBG> DISPLAY/MARK EXAM AT Q2 DO (EXAMINE A,B,C) 

prompts for input. Any changed values are highlighte . 

8 DBG_3> DISPLAY/PROCESS OUT_X AT S4 

This command makes display OUT_X specific to the visible process (process 
3) and puts the display at window S4. 

9 . DBG_2> DISPLAY/PROCESS OUT_/SUFFIX AT S45 OUTPUT 

This command creates an output display at window S45. By default 

the prompt. Therefore, the full display name is OUT_2. 




DO 


DO 


Executes a debugger command in the context of one or more processes. 
valueMULTIPBOcS debUgging COnflguration <when DBG$PROCESS has the 


Format 


Qualifiers 


DO (commandf; . . . ]) 


Parameters 


command 

52SLV3ST command that is to be executed ta the contat ° f the 


/PROCESS=(process-spec[, ... ]) 

Specifies one or more processes in whose context the commands are executed 

not 1 s^edfy^ROCESS^ th entheS6S T* * ^ Spedfy ° nly ° ne process ' If you do 
fth • !ff i CE ® S ’ th ® com mands are executed in the context of all processes 

proirfScX 80 y ° U SPe0ify ““ asterisk <*> wildcard character for 


Use any of the following forms: 
[%PROCESS_NAME] proc-name 

[%PROCESS_NAME] "proc-name" 

%PROCESS_PID proc-id 

%PROCESS_NUMBER proc-number 
(or %PROC proc-number) 

proc-group-name 

%NEXT_PROCESS 


The process name, if that name 
contains no space or lowercase 
characters. The process name can 
include the asterisk (*) wildcard 
character. 

The process name, if that name 
contains space or lowercase 
characters. You can also use 
apostrophes (') instead of quotation 
marks ("). 

The process identification number 
(FTD, a hexadecimal number). 

The number assigned to a process 
when it comes under debugger 
control. Process numbers appear 
in a SHOW PROCESS display. 

A symbol defined with the DEFINE 
/PROCESS_GROUP command to 
represent a group of processes. 

Do not specify a recursive symbol 
definition. 

The process after the visible process 
in the debugger’s circular process 
list. 
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DO 


Description 


Examples 


%PREVIOUS_PROCESS 

%VISIBLE_PROCESS 


The process previous to the visible 
process in the debugger’s circular 
process list. 

The process whose call stack, register 
set, and images are the current 
context for looking up symbols, 
register values, routine calls, 
breakpoints, and so on. 


By default, commands are executed in the context of to visible_p™*ss. The 
DO command enables you to execute commands in the context of one or more 
nroces^eTthat are currently under debugger control (this is also referred to 
as°' broadcasting" commands to processes). The DO command is equivalent to 
entering a SET PROCESS-VISIBLE command for each process specified mtht 
“kOCESS qualifier (or for all processes, if /PROCESS is not speeded) and then 
entering the specified commands. 

To change the visible process, use the SET PROCESS command. 

When using the DO command, note that a hold condition in the visible process 
(as established with the SET PROCESS/HOLD command) is ignored. 

Related command: SET PROCESS. 


l. 


DBG 2> DO (SHOW CALLS) 

For %PROCESS_NUMBER 1 

module name routine name 
*M0D4 SUB3 

For %PR0CESS_NUMBER 2 

module name routine name 
*M0D3 SUB1 

DBG 2> 


line 

31 

rel PC 
0000001E 

abs PC 
0000041E 

line 

4 

rel PC 
0000000B 

abs PC 
0000040B 


This command executes a SHOW CALLS command in the context of all 
processes that are currently under debugger control. 


2. DBG3> D0/PR0CESS=(%PR0C 2,%PR0C 1) (EVAL/ADDR X;EXAMINE X) 

For %PR0CESS NUMBER 2 , , , .. hl 

%DEBUG-E-NOSYMBOL, symbol 'X' is not in the symbol tab 

for ^Process number 1 


512 

TEST\X: 1 
DBG_3> 

This command executes the two commands EVAL/ADDR X and EXAMINE X 
in the context of processes 2 and 1. 
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EDIT 


EDIT 


Format 


Parameters 


fSe?atETEm'?OR bliShed 'f' SET EDIT0E If you did not 

WmSS C ° mma " <1 ’ starts the DEC Language-Sensitive Editor 
it that editor is installed on your system. 


EDIT [[module-name\] line-number] 


module-name 

n^ C1 f eS the name of the module whose source file is to be edited. If you specify a 

parameterXe y s 0 o U urcr S fii alSO h SPeCi ^ * ^ nUmber If you omit the module name 
chosen for’edhing 86 ^ “ the CUrrent source «*** is 

line-number 

A posdtiye integer that specifies the source line on which the editor’s cursor is 
POSITIOmseeThfsET EDITOlfcommandJ ^ ™ Se * to /N “- 


Qualifiers 


Description 


/EXIT 

/NOEXIT (default) 

you n specX*HTr. d n K the debUgging SeS8i ° n Pri0r *° starti ”S the editor. If 
”7 /EXIT ' th f ^bugging session is terminated and the editor is then 

vn a , If y ° U specify /N0EXIT ’ the editing session is started and you return to 
your debugging session after terminating the editing session. 


If you have not specified an editor with the SET EDITOR command the EDIT 

ruZo“sstfl %ZT ECL rrr Sensitive Editor <lsedit) ^— 

use the EDTT crff , ?! ° n y ° Ur SystemX The typicaI (default ) way to 

he EDIT command is not to specify any parameters. In this case the editing 

cursor is initially positioned at the beginning of the line that is centered in the § 

currently selected debugger source display (the current source dispky) 

The SET EDITOR command provides options for starting different editors either 
in a subprocess or through a callable interface. ’ ™ 


Related commands: 

(SET,SHOW) EDITOR 
(SET,SHOW,CANCEL) SOURCE 
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EDIT 


Examples 


dbg> edit 

This command spawns the DEC Language-Sensitive Editor (LSEDIT) in a 
subnrocess^o edit the source file whose code appears in the current source 
display. The editing cursor is positioned at the beginning of the line a wa 
centered in the source display. 

DBG> EDIT SWAP\12 

This command spawns the DEC Language-Sensitive EditorOSEDTOi a 
subprocess to edit the source file containing the module SWAP- The editing 
cursor is positioned at the beginning of source line 12. 

DBG> SET EDITOR/CALLABLE_EDT 
DBG> EDIT 

Tn thi - example the SET EDITOR/CALLABLE_EDT command establishes 
default editor and is started tjnmugh its^aHemtorface 
(rather than spawned in a subprocess). The EDIT command 8 
edit the source file whose code appears in the current source display. The 
editing cursor is positioned at the beginning of source line 1, because the 
default qualifier /NOSTART_POSITION applies to EDT. 
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ENABLE AST — 

Enables the delivery of asynchronous system traps (ASTs) in your program. 

Format 


ENABLE AST 


Description 


The ENABLE AST command enables the delivery of ASTs while vnnr 
runmng including any pending ASTs (ASTs waiting to be delivered) If ASTs Zre 

STueued and T (P-essing"commands and so ot^he? 

ofX" dellvered when con trol is returned to the program. Delivery 

of ASTs in your program is initially enabled by default. ^ 


Note 


Any caH by your program to the $SETAST system service that disables 
ASTs overrides a previous ENABLE AST command. 


Example 


Related commands: (DISABLE,SHOW) AST. 


DBG> ENABLE AST 
DBG> SHOW AST 
ASTs are enabled 
DBG> 


The ENABLE AST command enables the delivery of A<?Ta ir, , 

confirmed with the SHOW AST command. 7 y program ’ as 
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EVALUATE 


EVALUATE 


Displays the value of a language expression in the current language (by default, 
the language of the module containing the main program). 


Format 


EVALUATE language-expression[, .. • ] 


Parameters 


Qualifiers 


language-expression 

Specifies any valid expression in the current language. 


/BINARY ,. 

Specifies that the result be displayed in binary radix. 

sSdfiel'ttiat'the expression be interpreted as a condition value (the land of 
condition value you would specify using the condition-handling mechams 0- 
Tl message text corresponding to that condition value is then displayed. The 
specified value must be an integer value. 

/DECIMAL , . , . . 

Specifies that the result be displayed in decimal radix. 

/HEXADECIMAL , . . ,. 

Specifies that the result be displayed in hexadecimal radix. 

Specifies that the result be displayed in octal radix. 


Description 




The debugger interprets the expression specified in an EVALUATE command 1 as, a 
the current language. 

The current language is the language last established with the SET LANGUAi 
I he current lang g a SET LANGUAGE command, the current 

language is! by default, the language of the module containing the mam program. 

Tf an exDression contains symbols with different compiler-generated types the 
debugger uSs the type-conversion rules of the current language to evaluate the 

expression. 

The debugger can interpret and display integer data in any one of four radbtes: 
binary! dedmal, hexadecimal, and octal. The current radix is the radix last 
established with the SET RADIX command. 

If you did not enter a SET RADIX command, the default radix for both data entry 
and display is decimal for most languages. 

On VAX processors, the exceptions are BLISS and MACRO-32, which have a 
default radix of hexadecimal. ♦ 
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EVALUATE 


Alpha 


Alpha 


Examples 


MACRO - 32 ’ ” d MACRO - 64 ' 

SSSSsSS- 

:==sjssas;*“ 

SlTifraoDnrV an T ge t exp T sta that includes a fu "' tion «1I- For 

the“mma„d SIltlSS"?*" * W ° inteBerS " y<W ““ 

variable. 3 *“*“ * * 


te&ss-ts »•„ 

^ ^ <*— and 

Related commands: 


EVALUATE/ADDRESS 

MONITOR 

(SET,SHOW) LANGUAGE 
(SET,SHOW,CANCEL) RADIX 
(SET,SHOW) TYPE 


1 . DBG> EVALUATE 100.34 * (14 2 + 7 0) 
2217.514 ' 

DBG> 


( T 14 iS 2 C + °7.9) and USGS the debugger as a calculator by multiplying 100.34 by 


2 . DBG> EVALUATE/OCTAL X 
00000001512 
DBG> 


This command evaluates the symbol X and displays the result in octal radix. 

3. DBG> EVALUATE TOTAL + CURR AMOUNT 
8247.20 
DBG> 


This command evaluates the 
and CURR_AMOUNT. 


sum of the values of two real variables, TOTAL 


4. DBG> DEPOSIT WILLING = TRUE 
DBG> DEPOSIT ABLE = FALSE 
DBG> EVALUATE WILLING AND ABLE 
False 
DBG> 


In this example, the EVALUATE command evaluates the logical AND of the 
current values of two Boolean variables, WILLING and ABLE. 
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EVALUATE 


5 . dbg> evaluate color'first 
RED 
DBG> 

In this Ada example, this command evaluates the first element of the 
enumeration type COLOR. 
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EVALUATE/ADDRESS 


Format 


Parameters 


a E reSt 8 „ a a n m a ' dreS8 eXPre8Si ° n a “ d the "«"■» <* a mem 01y address or 


EVALUATE/ADDRESS address-expression[, ... ] 


Qualifiers 


Description 


address-expression 

sszrsi z ssr«-— a , 


/BINARY 

Displays the memory address in binary radix. 

/DECIMAL 

Displays the memory address in decimal radix. 

/HEXADECIMAL 

Displays the memory address in hexadecimal radix. 

/OCTAL 

Displays the memory address in octal radix. 




Alpha 


SSSZS S£Z expression 61 ™ 116 ‘ he 

The debugger can interpret and display integer data in fl nv „ ff 

SSStSr are BUSS “ 4 MACBO - 32 - -e a 

MACBO - 32 - and MACR( ^ 64 ' 

but nKetput radix. ^ ‘ S ' °'" Srrid '> the »utpSt radix, 

successors WNEXTLOC) are based on the value of ^ 
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EVALUATE/ADDRESS 


Alpha 


Examples 


routine, entry point, or Ada package. ♦ 
Related commands: 


EVALUATE 

(SET,SHOW,CANCEL) RADIX 
SHOW SYMBOL/ADDRESS 
SYMBOLIZE 


1. DBG> EVALUATE/ADDRESS MODNAMEULINE 110 
3942 

DBG> 

This command displays the memory address denoted by the address 

expression MODNAME\%LINE 110. 

2. DBG> EVALUATE/ADDRESS/HEX A,B,C 
000004A4 

000004AC 

000004A0 

DBG> 

This command displays the memory addresses denoted by the address 
expressions A, B, and C in hexadecimal radix. 

3. DBG> EVALUATE/ADDRESS X 

M0D3\%R1 

DBG> 

This command indicates that variable X is associated with register Rl. X is a 
nonstatic (register) variable. 
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EXAMINE 


—“° re - 


Format 


Parameters 


EXAMINE 


[address-expression[:address-expression] 


Qualifiers 


address-expression 

nlftf a“aS and'crSl *• is WUr the 

the Built_inJ3yrnbols and AddrijIxpJl^’^i^ ™ 

fte^ a „nEf«z^tr n1, array slice ' or record compoMnt - M, °” 

SisSFi=-— 

exS2 y tte 6 next r dd T eXPreS8i °”’ the >^ZesZ7f£l SdrL 

sSSSSS 3 - - *:KSSMW 

and vector instructions ’ see /tmask, 


/ASCIC 

/ASCID 

to an P ASCIi a string ai The d €LASS and'oTYPE fill’d * ?‘| ine , deSCnptor Pointing 
checked, but the LENGTH anj pSn^L ^descnptor are not 

■“* The ^ is *- 
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EXAMINE 


Alpha 


the type of the address expression. 

can also specify this qualifier as /AW. 

also specify this qualifier as /AZ. 

/BINARY . 

Displays each examined entity as a binary mteg . 

Displays each examined entity in the byte integer type (length 1 byte). 

Inte^rets^each^examined entity as a condition-value return status and displays 
the message associated with that return status. 

Displays each examined entity in the D_floating type (length 8 bytes). 

dd-mmm-yyyy hhmm.ss.cc. 

/DECIMAL , . , . . 

Displays each examined entity as a decimal integer. 

Displays each examined entity in the default radix. 

The minimum abbreviation is /DEFA. 

/DEFINITIONS=n 

saBMtasKBMHSSL 

aw^iill)^ the™ the ninnbe^trf additionaTdefiidtions^^reporte^as^ed^iFoi'^nore 
information on split-lifetime variables, see Chapter 13. ) 

The minimum abbreviation is /DEFI. ♦ 
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EXAMINE 


/EXTENDED FLOAT 


Alpha 


40 ^ 


Alpha 


Alpha 






Alpha 


aenXsCsT'." 31 ’ 155 ' 8 eaCh “ amined “ t,ty in the IEEE *-*»«"* 


/FLOAT 


4°CS ~ rS ’ diSPlayS each eXamiMd en “y *> «- F-floating type (length 
flengt&w e “ Mtity " ^ IEEE “g 


/FPCR 


c°onW eaCh eXamined “‘ ity iD FPCR ^floating-point 

/FMASK[=(mask-address-expression)] 

Applies to VAX vectorized programs. See the /TMASK qualifier. ♦ 

/G_FLOAT 

Displays each examined entity in the G_floating type (length 8 bytes). 

/H.FLOAT 

MeIt X e SyStemS ’ diSP ‘ ayS MCh examined entit y <” toe ^floating type (length 16 

/HEXADECIMAL 

Displays each examined entity as a hexadecimal integer. 

/INSTRUCTION 

addressing modes used). See also the /OPERANDS qualifier 

arrow m the instruction display points to the examine!instruction* 

/LINE (default) 

/NOLINE 

( C %LINE%W ther PI '? gram l0Cati0nS are dis Played in terms of line numbers 
( LINE x) or as routine-name + byte-offset Bv default f/T ^ a u 

symbolizes program locations in terms oOne nnm“ *' th6 debUgger 
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EXAMINE 


Alpha 


Alpha 




/LONG_FLOAT 

On Alpha processors, displays each examined entity in the IEEE S.floating type 
(single precision, length 4 bytes). ♦ 

/LONG_LONG_FLOAT 

On Alpha processors, displays each examined entity in the IEEE ^floating type 
(double-precision, length 8 bytes). ♦ 

type. 

/OCTAL 

Displays each examined entity as an octal integer. 

Eteplays^each examined entity in the octaword integer type (length 16 bytes). 

/OPERANDS[=keyword] 

0ri VAX nrocessors displays operand information associated with an examined 
instructien (display’s each 

SSK5 is /OPERANDS=BRIEF. 

that instruction. 

In screen mode, operand information is directed at the current output display. 

vector register that you can examine. 

c w iVip SFT MODE [NO]OPERANDS ^keyword command, which lets you set 
a deMtt,STe“ of operand information displayed when exammmg 

instructions. ♦ 

Interprets^ach examined entity as a packed decimal numhen Rvalue ef » is 
the number of decimal digits. Each digit occupies one nibble (4 bits). 
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EXAMINE 


Alpha 


/PS 


»fo~ rs ’ displays each examined entity in ps to"— 


status 


/PSL 


• displays each ““to* to PSL (processor 


longword) format. 

/PSW 


status 


P r °cessors, displays each examined entity in PSW (processor static 

except that on^TeZ^ 


order word 


(2 bytes) is displayed. ♦ 

/QUADWORD 

Displays each examined entity in the quadword integer type (length 8 bytes). 


/S_FLOAT 


Alpha 


Same as /LONG_FLOAT. ♦ 

/SFPCR 


Alpha 


r h esamined entity in sfpcr <—»» 


floating- 


/SOURCE 


Note 


de h bugger Mer * "°‘ aVa ‘ Iable ta ‘ he D EC™<lows Motif interface to the 


ThtTexainined'enrt c , or K reSpondin 8 to *<> location of each examined entity. 
uirefc^Tm d , S?‘ y , be associated with a machine code instruction and 

dTe - - »‘“ d 
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EXAMINE 


Alpha 


Alpha 


4^ 


package. ♦ 

/SYMBOLIC (default) 

suppresses°symbolization of entities you ^ absolute a ^ es ™ s ^ZuC 

not need to convert numbers to names. 

Lfk S mS examining P a task object, use /TASK only if the programing 
language does not have built-in tasking services. 

/T FLOAT 


Same as /LONG_LONG_FLOAT. ♦ 

/TMASK[=(mask-address-expression)] 

/FMASK[=(mask-address-expression)] 

On VAX processors, these qualifiers apply to VAX vectorized programs. They 
?naHe^ou to specify a mask in order to display certain elements of a vector 
register (VO to V15), or of an array in memory, while not displaying o er 

elements. 

For example when you examine the operands of a vector instruction (by using 
the /OPERANDS qualifier), these qualifiers enable you to overrule any operand- 
element masking that might be associated with that instruction. 

T , ™ MA c K aualifier applies the EXAMINE command only to the elements of 

SSSSSStrr 

vector length register (VLR) limits the highest register element that you 
examine but not the highest array element. 

“^“nd^toftefe °Mte Tin*4 el ^ e, rf/^Kr^ r d^“ te (in of 

/FMASK) ofVMR. 

If vou specify a mask address expression with /TMASK or /FMASK, the value at 
that address is used as the mask, subject to the following conventions. 

. You must use parentheses around the address expression. 
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EXAMINE 


’ “at you^n e f x^ne elemen ‘ 8 ^ nUmber ° f ° r *n-ay Amenta 

If the mask address expression denotes a Boolean array, its values are used 
as the mask, m the same basic way that VMR is used in the default case. 

If tha ma sk address expression denotes a non-Boolean array the least 

rfr blt V f 1Ue ° f ^ array element is used a * the mask for the 
corresponding element of the register or target array 

If the mask address expression denotes a Boolean scalar type its value 

s. ir.r.t.tiS 

No other elements are examined. g y 

1 r uJti ; elemen * ™ a f k. the lowest specified element of the mask is applied 
to the lowest specified element of the register or target array. . PP 

/TYPE=(name) 

Interprets and displays each examined entity according to the type specified 
by name (which must be the name of a variable or data type dedared in the 
program). This enables you to specify a user-declared type. You must use 
parentheses around the type expression. 

/X FLOAT 


Alpha 


Description 


Alpha 


Same as /EXTENDED_FLOAT. ♦ 

/WORD 

Displays each examined entity in the word integer type (length 2 bytes). 

The EXAMINE command displays the entity at the location denoted by an 
address expression. You can use the command to display the contents of anv 
memory location or register that is accessible in your program For high-level 

SKT iS USGd m ° StIy t0 ° btain the "-Sit value of a variable 

(an integer, real, string, array, record, and so on). 6 

*LTTrr.’J {y0U are debugging optimized code, the EXAMINE command 
splays the definition points at which a split-lifetime variable could have 

ZZf £ variaMes are discussed in ch e a “™ 

SSS^SS^ COmmand dlSplayS up t0 five definition points. With the 
/Ubt INITIONS qualifier, you can specify the number of definition points. ♦ 

J?l debagger recogldzes the compiler-generated types associated with symbolic 
dress expressions (symbolic names declared in your program) Symbolic 
address expressions include the following entities. symbolic 

Variable names. When specifying a variable with the EXAMINE command 
use the same syntax that is used in the source code. command, 

mi!r nam v labelS ’ and line numbers - These are associated with 
when exZlinl^MeT™ mStrUCti ° nS USing the same Uniques as 
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EXAMINE 


In general, when you enter an EXAMINE command.thedebugger 
the address expression specified to yield a program location. The debugg 
displays the value stored at that location as follows: 

. If the location has a symbolic name, the debugger ‘ he val “* “T*'" 8 

to the compiler-generated type associated with that symbol (that is, as a 
variable of a particular type or as an instruction). 

. If the location does not have a symbolic name (and, therefore no associated 

displays the contents of these locations as longword (4-byte) integer values. 




Alpha 


For information specific to vector registers and vector instructions, see the 
/TMASK, /FMASK, and /OPERANDS qualifiers. ♦ 

There are several ways of changing the type associated with a program location 
XTU the data at that location in another data format: 

. To change the default type for all locations that do not have a symbolic name, 
you can specify a new type with the SET TYPE command. 

• lb change the default type for all locations (both those thaUIo and do not 
have a symbolic name), you can specify a new type with the SET TYP 
/OVERRIDE command. 

. To override the type currently associated with a particular location for the 
duration of a single EXAMINE command, you can specify a new type by using 
a type qualifier (/ASCILra, /BYTE, /TYPE ={name), and so on). Most qualifiers 
for the EXAMINE command are type qualifiers. 

The debugger can interpret and display integer data in any one of four radixes: 
binary, decimal, hexadecimal, and octal. 

The default radix for both data entry and display is decimal for most languages. 

On VAX processors, the exceptions are BLISS and MACRO-32, which have a 
default radix of hexadecimal. ♦ 

On Alpha processors, the exceptions are BLISS, MACRO-32, and MACRO-64, 
which have a default radix of hexadecimal. ♦ 

The EXAMINE command has four radix qualifiers (/BINARY, 

/HEXADECIMAL /OCTAL) that enable you to display data in another radix. 

^n also use the SET RADIX and SET RADIX/OVERRIDE commands to change 

the default radix. 

In addition to the type and radix qualifiers, the EXAMINE command has 
qualifiers for other purposes: 

• The /SOURCE qualifier enables you to identify the line of source code 
Responding to a line number, routine name, label, or any other address 
expression that is associated with an instruction rather than data. 

• The /[NOILINE and /[NOISYMBOLIC qualifiers enable you to control the 
symbolization of address expressions. 

The EXAMINE command sets the current entity built-in symbols ^fURLOC 
and period (.) to the location denoted by the address expression specified. Logical 
predecessors (%PREVLOC or the circumflex character < )) and successo 

(%NEXTLOC) are based on the value of the current entity. 
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Related Commands: 

CANCEL TYPE/OVERRIDE 

DEPOSIT 

EVALUATE 

SET MODE [NOJOPERANDS 
SET MODE [NO]SYMBOLIC 
(SET,SHOW,CANCEL) RADIX 
(SET,SHOW) TYPE 

Examples 

1. DBG> EXAMINE COUNT 
SUB2\COUNT: 27 
DBG> 


SUB2° mmand dlSplayS the value of the inte ger variable COUNT in module 


2. DBG> EXAMINE PART_NUMBER 

INVENTORY\PART NUMBER: "LP-3592 6-84" 
DBG> 


This command displays the value of the string variable PART_NUMBER. 


3. DBG> EXAMINE SUB1\ARR3 
SUB1\ARR3 


( 1 , 1 ) 
( 1 , 2 ) 

(1.3) 
(2,1) 
( 2 , 2 ) 

(2.3) 
DBG> 


27.01000 

31.01000 

12.48000 

15.08000 

22.30000 

18.73000 


SUBr°Sl d if ; y V h f val, ) e ° f a “ elemente in arra y ARM i” module 
UB1. ARR3 is a 2 by 3 element array of real numbers. 


4. DBG> EXAMINE SUB1\ARR3 (2,1:3) 
SUB1\ARR3 

(2.1) : 15.08000 

(2.2) : 22.30000 

(2, 3): 18.73000 

DBG> 


gul\7™ nd 1 ? spl . ay8 the , of the elements in a slice of array 
SUB1\ARR3. The slice includes "columns" 1 to 3 of "row" 2. 


5. DBG> EXAMINE VALVES.INTAKE.STATUS 
MONITORWALVES. INTAKE. STATUS: OFF 
DBG> 


^ 1 T S t ^ mand displa ^ s the value of the nested record component 
VALVES.INTAKE.STATUS in module MONITOR. 


6 . 


DBG> EXAMINE/SOURCE SWAP 
module MAIN 

n 47: procedure SWAP (X, Y: in out INTEGER) is 


This command displays the source line in which 
(the location of routine SWAP). 


routine SWAP 


is declared 
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7. 


DBG> DEPOSIT/ASCII:7 WORK+20 = 'abcdefg' 
DBG> EXAMINE/ASCII:7 WORK+20 
DETAT\WORK+20: "abcdefg" 

DBG> EXAMINE/ASCII:5 WORK+20 
DETAT\WORK+20: "abode" 


DBG> 

In this example, the DEPOSIT command deposits the entity ' abcdefg' as 
In ASCII String of length 7 bytes into the location that is 20 bytes beyond 
the^ocatio^^enotedTby^the symbol WORK The 

Hisnlavs the value of the entity at that location as an ASCII string ol iengt 
7 bytes (abcdefg). The second EXAMINE command displays the value of the 
entity at that location as an ASCII string of length 5 bytes (abcde). 


o DBG> EXAMINE/OPERANDS-FULL .0\%PC 
X\X$START+OC: MOVL B A 04(R4),R7 


B a 04(R4) 


R7 


R4 contains X\X$START\M (address 00001054), 
B A 04 (00001054) evaluates to X\X$START\K 
(address 00001058), which contains 00000016 
R7 contains 00000000 


DBG> 


On VAX systems, this command displays the instruction (MOVL) at the 
current PC value. Using /OPERANDS=FULL displays the maximum level of 

operand information. ♦ 


9. 


DBG> set radix hexadecimal 

DBG> EVALUATE/ADDRESS WORKDATA 
0000086F 

DBG> EXAMINE/SYMBOLIC 0000086F 

MOD 3WORKDATA: 03020100 

DBG> EXAMINE/NOSYMBOLIC 0000086F 


0000086F: 03020100 

DBG> 


Tr. this example the EVALUATE/ADDRESS command indicates that the 
memorv address of variable WORKDATA is 0000086F, hexadecimal. The 
two EXAMINE commands display the value contained at that a ddres^usmg 
/rNOlSYMBOL to control whether the address is symbolized to 


10 . 


dbg> examine/hex FIDBLK 
FDEX1$MAIN\FIDBLK 

(1): 00000008 

( 2 ); 00000100 

(3) : OOOOOOAB 

DBG> 

This command displays the value 
hexadecimal radix. 


of the array variable FIDBLK in 


u. DBG> EXAMINE/DECIMAL/WORD NEWDATA:NEWDATA+ 6 
SUB2\NEWDATA: 256 
SUB2\NEWDATA+2: 770 
SUB2\NEWDATA+4: 1284 
SUB2\NEWDATA+ 6: 1798 


DBG> 


This command displays, in decimal radix, the values of word integer entities 
(2-bvte entities) that are in the range of locations denoted by NEWDATA to 


NEWDATA + 6 bytes. 
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12. DBG> EXAMINE/TASK SORT INPUT 
MOD3\SORT INPUT: %TASK 12 
DBG> 

This command displays the task ID of a task object named SORTJNPUT. 
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EXIT 


a command procedure or DO clause and no process is specified, it exits th 
command procedure or DO clause at that point. 


Format 

EXIT [process-spec[, ... ]] 


Parameters 


ms parameter applies to a multiprocess debugfpng configuration (when 
DBG$PROCESS has the value MULTIPROCESS). 

Specifies a process currently under debugger control. Use any of the following 
forms: 

The process name, if that name 




[%PROCESS_NAME] proc-name 

[%PROCESS_NAME] "proc-name" 

%PROCESS_PID proc-id 

%PROCESS_NUMBER proc-number 
(or %PROC proc-number) 

proc-group-name 

%NEXT_PROCESS 
%PREVTOU S_PROCESS 


characters. The process name can 
include the asterisk (*) wildcard 
character. 

The process name, if that name 
contains space or lowercase 
characters. You can also use 
apostrophes (') instead of quotation 
marks ("). 

The process identification number 
(PID, a hexadecimal number). 

The number assigned to a process 
when it comes under debugger 
control. Process numbers appear 
in a SHOW PROCESS display. 

A symbol defined with the DEFINE 
/PROCESS_GROUP command to 
represent a group of processes. 

Do not specify a recursive symbol 
definition. 

The process after the visible process 
in the debugger’s circular process 
list. 

The process previous to the visible 
process in the debugger’s circular 
process list. 
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EXIT 


Description 


%VTSIBLE_PROCESS T , , 

I he process whose call stack, register 
set, and images are the current 
context for looking up symbols, 
register values, routine calls, 
breakpoints, and so on. 

You can also use the asterisk (*) wildcard character to specify all processes. 


““x r: can be used to 

Ending a Debugging Session 

whhout a ii f gging SeSSi ° n ’ Gnter thG EXIT command a t the debugger prompt 
without specifying any parameters. This causes orderly termination ofthe 

session, the program’s application-declared exit handlers (if any) are executed 

is “ <d08ing log mes ' SZSSi 

Ynlm,?! d . ’ d C ° ntro1 18 returned to the command interpreter. 

DEBUG or CONt'i^ the DCL ~nd 

Berause EXIT runs any application-declared exit handlers, you can set 

EXIT. tL! yTcln^ Upon <*** 


Using the EXIT Command in Command Procedures and DO Clauses 

When the debugger executes an EXIT command (without any parameters) in 

thp 0 ^ 111311 procedure > con trol returns to the command stream that invoked 
he command procedure. A command stream can be the terminal an outer 
(contammg) command procedure, or a DO clause in a command or’screen disnlav 

nS e ,w e de . bUggel ' executes “ EXIT (without any parameters) in a 

pmmpt ,Sn0reS ^ C ° mmands “ daui and dispiysTts 

Terminating Specified Processes 

If you are using the multiprocess debugging configuration to u- 

program (if the logical name DBG$PROGESS has^he va”ue WLTIPROCES^ 8 

r szS'JSL'1 st **v te r nate " 

exit handlers associate! with fhese 
PROCESS/,u a f V ’ h ,r 8peclfi<id Processes are no longer identified in a SHOW 

SSSSd; f any T t fi d , t T e8ses were h ° ld “ resulted a 
oni rKUC/Ebb/HOLD command, the hold condition is ignored. 
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EXIT 


Examples 


When the specified processes begin to 

hold begins execution. ter execu 'on 1 [NOIINTERRUPT command. By 

any pniSss At that point, execution is interrupted in any other processes that 
were executing images, and the debugger prompts for mpu . 

To terminate specified processes without running any application-declared exit 
LlTs oTotherwise starting execution, use the QUIT command instead of 

EXIT. 

Related commands: 

DISCONNECT 
@ (Execute Procedure) 

Ctrl/C 

Ctrl/Y 

Ctrl/Z 

QUIT 

RERUN 

RUN 

SET ABORT_KEY 

SET MODE [NOIINTERRUPT 

SET PROCESS 


2 . 


dbg> exit 
$ 

This command ends the debugging session and returns you to DCL leve . 

JONES 1> EXIT %NEXT_PROCESS, %PROCESS_NAME J0NES_3, %PR0C 5 
J0NES~1> 

This command causes orderly termination of three fl ^ 
program: the process after the visible process on the process list,_ proces 
JONES.3, and process 5. Control is returned to the debugger after the 
specified processes have exited. 
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EXITLOOP 


EXITLOOP 


Format 


Parameters 


Exits one or more enclosing FOR, REPEAT, or WHILE loops. 
EXITLOOP [integer] 


integer 

defeult m i“ 1 l“ teSer SPeCifieS **“ nUmber ° f nested ‘"ops to from. The 


Description 


Example 


WHILE I™" C ° mmand t0 exit 0ne or more enclosing FOR, REPEAT, or 

Related commands: 

FOR 

REPEAT 

WHILE 


DBG> WHILE 1 DO (STEP; IF X .GT. 3 THEN EXITLOOP) 

he WHILE 1 command generates an endless loop that executes a STEP 
commajid with each iteration. After each STEP, the value o“x1a LtlTlf X 

examphfh ’ ™ TW ° P C ° mm “ d to™»a,es the loop 
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EXPAND 



EXPAND 


Expands or contracts the window associated with a screen display. 

_Note -- 

This command is not available in the DECwindows Motif interface to the 


debugger. 



Format 

EXPAND [display-name[, .. . ]] 

Parameters 

si P cMesTdMay to be expanded or contracted. You can specify any of the 
following entities: 

• A predefined display: 

SRC 

OUT 

PROMPT 

INST 

REG (VAX only) 

• A display previously created with the DISPLAY command 

• A display built-in symbol: 

%CURDISP 

%CURSCROLL 

%NEXTDISP 

%NEXTINST 

%NEXTOUTPUT 

%NEXTSCROLL 

%NEXTSOURCE 

If you do not specify a display, the current scrolling display, as established by the 
SELECT command, is chosen. 

You must specify at least one qualifier. 


Qualifiers 


1 line. 
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EXPAND 


Description 


/RIGHT[:n] 

Sr&ijf V he right by * (if " ' S »«*»> or 

right by 1 line. negative). If you omit n, the border is moved to the 

/SUFFIX[=process-identifier-type] 

^^vahi^MUI^I^oC^SS^A^ 11 ^ 011 ^^ 111 "^ 011 (when DBG $ Pp OCESS has 

aSSSr-a 

Use any of the following process-identifier-type keywords: 

PROCESS.NAME The display-name suffix is the process name 

CESS.NUMBER The toplay-name suffix is the process number (as shown 
in a SHOW PROCESS display). 

PROCESSED ££*£»» suffix is the process identification 

SS “» 

used for the prompt suffix (see the SET PROMPT/SUFFIX command™* ”* * ^ 

/UP[:n] 

SSSSsSSSS.'xssi SSSSS7 “ 

paM^ioa^^Dep^dhig^onThe 11 ^!^^^^^^ 0 !)^ ffis(days^lie^lXPAND^* S ^ a ^ d 

contacted or expanded horisontaiiy but can be c^S^fcT^of 
A window border can be expanded only up to the edge of the screen Thp W+ 

For a list of the key definitions associated with the FXPAlvm ™ j 
the Keypad.Definitions_CI help topic. Mso use thel^CT? ’ T 
determine the current key definitions. Y Command 
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EXPAND 


Examples 


Related commands: 

DISPLAY 

MOVE 

SELECT/SCROLL 
(SET,SHOW) TERMINAL 


1. DBG> EXPAND/RIGHT:6 

This command moves the right border of the current scrolling display to the 
right by 6 columns. 

2. DBG> EXPAND/UP/RIGHT:-12 0UT2 

This command moves the top border of display OUT2 up by 1 line, and the 
right border to the left by 12 columns. 

3. DBG> EXPAND/DOWN:99 SRC 

This command moves the bottom border of display SRC down to the bottom 
edge of the screen. 


CD-120 




EXTRACT 


EXTRACT 




Note 


debuggeT 8 ^ “ Mt aVai ‘ able in the DEC ™<i°ws Motif interface to the 


Format 


Parameters 


EXTRACT [display-name[_]] [file-spec] 


Qualifiers 


display-name 

Specifies a display to be extracted. You can specify any of the following entities: 

• A predefined display: 

SRC 

OUT 

PROMPT 

INST 

REG (VAX only) 

A display previously created with the DISPLAY command 

te Sl^u"^ “ 3 diSphy D ° R-fr 

file-spec 

Spedlies the file to which the information is written. You can specify a logical 

SSSSK default specification for the file is 
SYS$DISK:[ 1DEBUG.TXT. erwise, the default specification is 


/ALL 

Extracts all displays. Do not specify /SCREEN_LAYOUT with this qualifier. 

/APPEND 

/SCREEN_LAYOUT 

oTrs±.^ir”^at e nte 

position, display kind, and display attributes of eveiy elistingdtapty Thisffle 
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EXTRACT 


can then be executed with the execute procedure command («) to reconstruct the 
screen at a later time. 

/SUFFIX[=process-identifier-type] (when DBG$PROCESS has 

Applies to a multiprocess debugging configuratio ( display 

iSSSSSf 8 The suffix denotes 

the visible process at the time the command was issued. 

™ /cjttfFIX Qualifier is used primarily in command procedures when you specify 
ffispl"Xn1or definitions that are bound to display defimtions. 

Use any of the following process-identifier-type keywords. 

PROCESS NAME The display-name suffix is the process name. 

PROCESs'nUMBER The display-name suffix is the process number (as shown 

in a SHOW PROCESS display). 

PROCESS.PID The display-name suffix is the process identification 

number (PID). 

_ /^JTTTTFTX without a vrocess-identifier-typc keyword, the process 


Description 


n 11 wytrACT command to save the contents of a display into a 

file. 

You cannot extract the PROMPT display into a file. 

Related commands: 

DISPLAY 

SAVE 


Examples 


1 dbg> EXTRACT SRC 

This command writes all the lines in display SRC into file 
SYS$DISK:[ 1DEBUG.TXT. 

2 DBG> EXTRACT/APPEND OUT [JONES.WORK]MYFILE 

This command appends all the lines in display OUT to the end of 

[J0NES.W0RK1MYFILE.TXT. 

3. DBG> EXTRACT/SCREEN_LAYOUT 

This command writes the debugger conunands needed to reconstruct the 
screen into file SYS$DISK:l 1DBGSCREEN.COM. 
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FOR 


FOR 


Format 


Parameters 


number of times*” 0 * ° f Commands to-ementing a variable a specified 


F ° R ™m e =expression1 TO expression [BY expression^ 
DO (commandf; ... ]) 1 


Description 


Examples 


name 

Specifies the name of a count variable. 

expression! 

Sr itK vaiue - The 

expression2 

“ “mtXS Va ‘ Ue ' The “ d «*«*»* 

expressions 

Specifies an integer. 

command 

the syntax of any expresses in the commands and then evaluates S 

value of expressly™ 1 ^ ^ ValUG of expresswn3 until it is greater than the 

If expressions is zero, the debugger returns an error message. 

If expressions is omitted, the debugger assumes it to have the value +1. 

Related commands: 

EXITLOOP 

REPEAT 

WHILE 


1. DBG> FOR I - 10 TO 1 BY -1 DO (EXAMINE A(I)) 

This command examines an array backwards. 
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FOR 


2 . DBG> FOR I = 1 TO 10 DO (DEPOSIT A (I) = 0) 

This command initializes an array to zero. 
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GO 


Format 


Parameters 


Starts or resumes program execution. 


GO [address-expression] 


address-expression 

“f-program execution resume at the location denoted by the address 


Description 


STEP) be US6d eX6CUte ^ pr0gram (the others ar e CALL EXIT, and d 

might n ° W be initialized differently 

a GG c °mmand to resume execution from the current location causes 
the debugger to resignal the exception. This enables you to observe which 
application-declared handler, if any, next handles the exception. 

Entering a GO command to resume execution from a location other than thn 

STxceS 0n * ^ eXeCUti ° n ° f ^ applicati -dedared handler for 

<“»« * multiprocess 

note the following^dditiona) pohS ” MULTIPR0CES S). 

The GO command is executed in the context of the visible process but 
images in any other processes that are not on hold (through a SET PROCESS 
/HOLD command) are also allowed to execute. If you use the DO command 

is exemted inth^c'TT 11 ? t0 T & ° T ^ processes ’ the GO command 
,w! d Xt ° f each s P ecified Process that is not on hold but 

images in any other processes that are not on hold are also allowed to execute 
In all cases, a hold condition in the visible process is ignored 
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GO 


. After execution is sta^d, the way* 

[set MODE INTERRUPT), execution continues until it is suspended many 
that point, execution is interrupted in any other processes that 
were executing images, and the debugger prompts for input. 

Related commands: 


CALL 

DO 

EXIT 

RERUN 

SET BREAK 

SET MODE [NOIINTERRUPT 

SET PROCESS 

SET STEP 

SET TRACE 

SET WATCH 

STEP 


Examples 

1. DBG> GO 

%DEBUG-i'-EXITSTATUS, is ' %SYSTEM-S-NORMAL, normal successful completion' 

DBG> , 11 

This command starts program execution, which then completes success u y. 

2 . DBG> SET BREAK RESTORE 

DBG> GO ! start execution 


break at routine INVENTORY\RESTORE 
137: procedure RESTORE; 

DBG> GO 1 resume execution 


Tn this example the SET BREAK command sets a breakpoint on routine 
RESTORE The’first GO command starts program execution, which is then 
fusp™ded aUhe breakpoint on routine RESTORE. The second GO command 
mc.imp« fvxRcution from the breakpoint. 


3 . DBG> GO %LINE 42 

T his command resumes program execution at line 42 of the module in whic 
execution is currently suspended. 
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HELP 


Displays online help on debugger commands and selected topics. 


Note 


^ command is !' ot available in the DECwindows Motif interface to 

DEclXa debu P b“ ““Tnlt “ aVai,aWe ^ “■» “ • 


Format 


Parameters 


HELP topic [subtopic [...]] 


topic 

subtopic 

subtopic, qualifier, or parameter about which you want further 
namT ^ 7 ““ asterisk wildcard < * >■ “‘her singly or within a 


Description 


Example 


The debugger’s online help facility provides the following information about 
any debugger command, including a description of the comm3 s fol^ 
explanations of any parameters that can bespecifiedw£Se^ «mm^Ta^d 
explanations of any qualifiers that can be specified with the command 

To get information about a particular qualifier or parameter specify it as a 

£ *. a 

subtopics related W t a! a comnmnd^si^dfy an'asteriskT^ as^subtopk 1 ^ 3ny 

MW featUreS With this of the debugger, 

For heip on the predefined keypad-key functions, see the Keypad Definitions Cl 

dlmZ. ’ USB ^ SH ° W ^ C< ™ d *° determinfthe-JuSem key 


DBG> HELP GO 

This command displays help for the GO command. 
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IF 


Executes a sequence of commands if a language expression (Boolean expression) 
is evaluated as true. 


Format 


IF Boolean-expression THEN (command[; 
[ELSE (command[; ...])] 


Parameters 


expression that evaluates as a B^lean value (true or false) 
in the currently set language. 

Specifies*! debugger command. If you specif, more than one command, you must 
separate the commands with semicolons (;). 


Description 


The IF command evaluates a Boolean expression. If the value is true (asi defined 
m “ent language), the command list 

the expression is false, the command hst in the ELbE clause ui any; 

Related commands: 

EXITLOOP 

FOR 

REPEAT 

WHILE 


Example 


DBG> SET BREAK R DO (IF X .LI. 5 THEN (GO) ELSE (EXAMINE X>> 

This command causes the debugger to suspend program 

(a breakpoint) and then resume program execution if the value of X is less 

(FORTRAN example). If the value of X is 5 or more, its value is displayed. 
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MONITOR 


MONITOR 


Monitor View of the DECwindov^Motif interface.^ IangU3ge ex P ression in the 


Note 


Requires the DECwindows Motif interface. 


Format 


Parameters 


MONITOR expression 


Qualifiers 


expression 

Currently MONITOR (totfs SffT “ “ ~ 
expressions (language exp re ssio„Too“S,g 0S0”) 

Va f ria v e »«t. structure such 

r ii . a structure), the Monitor View lists “ApOTPo-ete” , i 

l^: n e^r^stn lick on the 
tt s S"S™t a i™^r nt ’ array slice ' or record comp ° ne " t - m °» 


/ASCIC 

Interprets each monitored entity as a counted A^fTT . 

count field that gives the length of the S The ct 8 a 1 ' byte 

can also specify this qualifier as /AC. *' 8 “ then dlsplayed - You 

/ASCID 

to ^^AS^lTstriTg 0 '^^^^ M^DTYPhTfields & 5*'j dnj ’. desc . ld P tor Pointing 
checked, but the LENGTH and POINTER field* S 0 th ^ des ^ n P tor are not 

/ASCIhn 

Interprets and displays each monitored entity as an ASfTT n n 

from^he t^ofThe aSs°^i^^ debUgBer t0 determine a length 

/ASCIW 
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MONITOR 




Alpha 




Alpha 


also specify this qualifier as /AZ. 

/BINARY , . . . M , 

Displays each monitored entity as a binary in g 

Displays each monitored entity in the byte integer type (length 1 byte). 

ID FLOAT 


On VAX processors, displays each monitored entity in the D_floating type (length 
8 bytes). ♦ 

Intop^ach monitored entity as a quadword *^splays 

containing the internal OpenVMS representation of date and time. Disp y 
the value in the format dd-mmm-yyyy hh:mm:ss.cc. 

/DECIMAL , . . . . 

Displays each monitored entity as a decimal in eger. 

Displays each monitored entity in the default radix. 

/EXTENDED_FLOAT 

On Alpha systems, displays each monitored entity in the IEEE X_floating type 
(length 16 bytes). ♦ 


/F_FLOAT 

On VAX processors 
4 bytes). ♦ 


, displays each monitored entity in the F_floating type (length 


On Alpha processors, displays each monitored entity in the IEEE T_floating 
double-precision (length 8 bytes). ♦ 

Ssplayf each monitored entity in the G_floating type (length 8 bytes). 

/H_FLOAT 

Displays each monitored entity in the H_floating type (length 16 byt 

/HEXADECIMAL . ... 

Displays each monitored entity as a hexadecimal integer. 
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MONITOR 


Description 


/INSTRUCTION 

addressing modes used). See also the /OPERANDS qualifier 

/LONGWORD 

/OCTAL 

Displays each monitored entity as an octal integer. 

/OCTAWORD 

Displays each monitored entity in the octaword integer type (length 16 bytes). 

/QUADWORD 

Displays each monitored entity in the quadword integer type (length 8 bytes). 

/REMOVE 

STillfc™* item 0r items ™ th the •*!««■ expression specified from 

/TASK 

language does n“ hTvebufiWn tasting rertces.^^ 01 " y * 0,6 pr0grammin S 

/WORD 

Displays each monitored entity in the word integer type (length 2 bytes). 
MoHnot US f the k M0NIT( ? E “■"'"and only with the debugger’s DECwindows 

“ew w ft Z ‘“■f?;'"' ° f that - Reeled at ZmZL 

or S^ATCH~nd?n“Z USe fl " EVALUATE - 

The MONITOR command does the following: 

MONITOR command Vl6W ^ * 1S n<>t already Splayed by a previous 


2 . 


MONITOR command). 

llTr Wow .* 6 SPedfied VariaMe ° r eXpreSSi0n and its v alue in 

a —a 

ScfeHit rmati ° n ab0Ut the Monitor View “ d «* MONITOR command, (see 
Related commands: 

DEPOSIT 

EVALUATE 
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MONITOR 


Example 


EXAMINE 
SET WATCH 


dbg> monitor count _ . 

updated whenever the debugger regains control from the program. 
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MOVE 


Moves a screen display vertically or horizontally across the 


screen. 


Note 


iS aVailable in the DECwi "<lows Motif interface 


to the 


Format 


MOVE [display-name[, ... ]] 


Parameters 


Qualifiers 


display-name 

Specifies a display to be moved. You can specify any of the following entities: 

• A predefined display: 

SRC 

OUT 

PROMPT 

INST 

REG (VAX only) 

A display previously created with the DISPLAY command 

• A display built-in symbol: 

%CURDISP 

%CURSCROLL 

%NEXTDISP 

%NEXTINST 

%NEXTOUTPUT 

%NEXTSCROLL 

%NEXTSOURCE 

SELECT commandfis choslm ^ SCr ° 1Iing displa * as established by the 

You must specify at least one qualifier. 


/DOWN[:n] 

“X* e i?yo!fC™ tdtXTsmovSSb^Cr Hf " * 8 

/LEFT[:n] 

/RIGHT[:n] 

“ liMs <if - is 
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MOVE 


/SUFFIX[=process-identifier-type] (when D BG$PROCESS has 

Applies to a multiprocess debugging configuratio ( display 

rrssastrsrf - 

the visible process at the time the command was issued. 

Use any of the following process-identifier-type keywords: 


PROCESS_NAME 

PROCESS.NUMBER 

PROCESS_PID 


The display-name suffix is the process name. 

The display-name suffix is the process number (as shown 
in a SHOW PROCESS display). 

The display-name suffix is the process identification 
number (PID). 


Description 


if cnprifv /SUFFIX without a process-identifier-type keyword, the process 

maintaining the relative position of the text within the window. 

The MOVE command does not change the order of a display onto® 

display, partially or totally. 

A display can be moved only up to the edge of the screen. 

determine the current key definitions. 

Related commands: 

DISPLAY 

EXPAND 

SELECT/SCROLL 

(SET,SHOW) TERMINAL 


Examples 


1. DBG> MOVE/LEFT 

This command moves the current scrolling display to the left by 1 column. 


2 . 


DBG> MOVE/UP:3/RIGHT:5 NEW_0UT 

This command moves display NEW.OUT up by 3 lines and to the right by 5 
columns. 
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QUIT 


QUIT 


Format 


Parameters 


pro^am (likf EOTTbLT’ ° ne ° r m0re processes ° f “ ™ltiproce SS 

specified, it exits the command procedure or DO “ 


QUIT [process-spec[, ... ]] 


process-spec 

*” 8 mult *P r °cess debuggin; 
DBG$PROCESS has the value MULTIPROCESS). 

forms^ GS 3 Pr ° CeSS currentl y un der debugger contro 


configuration (when 
Use any of the following 


[%PROCESS_NAME] proc-name 

[%PROCESS_NAME] "proc-name" 

%PROCESS_PID proc-id 

%PROCESS_NUMBER proc-number 
(or %PROC proc-number ) 

proc-group-name 

%NEXT_PROCESS 

%PREVIOUS_PROCESS 


The process name, if that name 
contains no space or lowercase 
characters. The process name can 
include the asterisk (*) wildcard 
character. 

The process name, if that name 
contains space or lowercase 
characters. You can also use 
apostrophes (') instead of quotation 
marks ("). 

The process identification number 
(PID, a hexadecimal number). 

The number assigned to a process 
when it comes under debugger 
control. Process numbers appear 
in a SHOW PROCESS display. 

A symbol defined with the DEFINE 
/PROCESS_GROUP command to 
represent a group of processes. 

Do not specify a recursive symbol 
definition. 

The process after the visible process 
in the debugger’s circular process 
list. 

The process previous to the visible 
process in the debugger’s circular 
process list. 
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QUIT 


Description 


%VISIBLE_PROCESS 


The process whose call stack, register 
set, and images are the current 
context for looking up symbols, 
register values, routine calls, 
breakpoints, and so on. 


You can also use the asterisk (*) wildcard character to specify all processes. 


exit handlers in your program. 

££ rS"hand.er iS —^ " Stfeltou 

SS "“ietag your program by entering the DCL command 
DEBUG or CONTINUE (you must restart the debugger). 

Using the QUIT Command in Command Procedures and DO Clauses 

the command procedure. A command stream^can_ e J^nu digplay 

command (if any remain in the command sequence). 

When the debugger executee a QUIT command 

DO clause, it ignores any remaining commands in that clause a P 
prompt. 

” fete St r-S f ctd processes without ending 
DO clause. 

Tb terminate one .more STS 
in a SHOW PROCESS/ALL display. 

In contrast to the EXIT command, the QUIT command does not cause any process 
to start execution. 


Related commands: 

DISCONNECT 
@ (Execute Procedure) 
Ctrl/C 
Ctrl/Y 
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QUIT 


Examples 


Ctrl/Z 

EXIT 

RERUN 

RUN 

SET ABORT_KEY 
SET PROCESS 


1. DBG> QUIT 
$ 

This command ends the debugging session and returns you to DCL level. 

WIT SliEXT - PRraS S. %PROCESS_NAME JOSES J, SPRO; 5 

ZS 3 ' and >> r “ e8s 5 - CoiM is returned to the debugger afta-Te 
specified processes have exited. dIter tne 
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REBOOT (Alpha Only) 


REBOOT (Alpha Only) 


Alpha 


system program. 

The REBOOT command. Debugger 

—S Alpha System-Code Debugger is a kernel debugger 
that is activated through the OpenVMS Debugger.) 

Before you issue Q^M^MpirDe^SwllnManml. These instructions 
allows you to debug. 

You must also have started the OpenVMS Debugger with the DEBUG/KEEP 
command. 


Format 


Description 


Examples 


REBOOT 

For complete information on using the System Code Debugger, see the OpenVMS 
Alpha Device Support Manual. 

Related commands: 

CONNECT 

DISCONNECT 


! DBG> REBOOT 

This command reboots the target machine where you will be debugging t e 
OpenVMS Alpha operating system and reruns your program. 
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REPEAT 


Executes 


a sequence of commands a specified number of times. 


Format 


Parameters 


Description 


Example 


REPEAT language-expression DO (command[; . . . ]) 

language-expression 

tote"“ y eXPreSSi ° n to the Curre "“y ** that evaluates to a positive 

command 

checks the s y „tas of a„ y 

J™ REPEAT command is a simple form of the FOR command. The RFPFAT 
FOR^ommand doe^^"^ l *^ aC " P ^ oCl ^ n ^'' aa ^ :a ^ R ^ V ^'t I ^ tS ^^"tcteto 1 that the 

Related commands: 

EXITLOOP 

FOR 

WHILE 


DBG> REPEAT 10 DO (EXAMINE Y; STEP) 

™“n 6 SepTiO 'Zes that ^ * ~ ° f *» — 
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RERUN 


RERUN 


Reruns the program currently under debugger control. 


Note 


Reauires that you started your debugging session with the DCL command 
DEBUG/KEEP and then executed the debugger RUN command. If you 
began yo^sessL with the DCL command RUN program-image instead, 
you cannot use the debugger RERUN command. 


Format 


Qualifiers 


RERUN 


when running or rerunning that program are applied, by default. 

more information on using the Heap Analyzer, see Ch p 

/SAVE (default) 

The /SAVE qualifier specifies that their state is saved, and /NOSAVE specifies 
wYtchedrehitive to the main program uni, (where executant restarts). 


Description 


HSssSS-SSSSBr- 

debugger control. 

The RERUN command terminates the image you were debugging and then 
DCL RUN/DEBUG command. 

") tom the^mtd^ggiug session, use the RUN command. 
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RERUN 


Examples 


Related commands: 

RUN (debugger command) 

RUN (DCL command) 

(ACTIVATE,DEACTIVATE) BREAK 
(ACTIVATE,DEACTIVATE) TRACE 
(ACTIVATE,DEACTIVATE) WATCH 


1. DBG> RERUN 

2. DBG> RERUN/NOSAVE 

Jf h hL C Q °r ma ? d r mnS the CUrrent pro ^ am without saving the current state 

^ the - “ — 

3. DBG> RERUN/ARGUMENTS="fee fii foo fum" 

This command reruns the current program with new arguments. 
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RUN 


RUN 


Brings a program under debugger control. 


Note 


Requires that you started your debugging session'^CLco:mmand 
tyfrTTG/KEEP If you began your session with the DCL command kuin 
pr!gm™ instead, you cannot use the debugger RUN command. 


Format 


Qualifiers 


RUN [program-image] 


Parameters 


Specift^'tblf executable image of the program to be debugged. Do not specify an 
image if you use the /COMMAND=cmd-symbol qualifier. 


Snerifi^^ii^of arguments. If you specify a quoted string, you might have to 
add quotation marks because the debugger strips quotes when parsing the string. 

/COMMAND="cmd-symbol" 

Specifies a DCL foreign command for running the program. 

Do not use this qualifier if you specify a program-image parameter. 

Do not specify a DCL command or any other command definition that was created 
with the SET COMMAND command. 

(Apph^oidy to workstation users.) Invokes the Heap Analyzer, a debugger 
feature that helps you understand how memory is used by your applicatio . 
more information on using the Heap Analyzer, see Chapter . 


Description 


If vou invoked the debugger with the DCL DEBUG/KEEP command, you can use 
thl debugger RUN command at any time during a debugging session to start a 

you to save the current state (activated or deactivated) of any breakpoints, 
tracepoints, and static watchpoints. 

For a discussion of passing arguments when you use the RUN or RERUN 
command, see Chapter 5. 
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RUN 


Examples 


Note the following restrictions about the debugger RUN command- 

‘ BCLTBZa^TeZZnT “» «»W -«* 

' J^°^ S tadS«:n a ctw' :0nneCt ^ to * —tog 

• E —JS ZS!XX£ .=? =. .EK2ts* 

Related commands: 

RERUN 

RUN (DCL command) 

Ctrl/Y-DEBUG (DCL command) 

DEBUG (DCL command) 


1. DBG> RUN EIGHTQUEENS 

DEBUG-I-INITIAL, language is C, module set to EIGHTQUEENS 

This command brings the program EIGHTQUEENS under debugger control. 

2 ' I SKeeF " S DISK3: [SHITaiMYeEOG.EXE" 

DBG> RUN/COMMAND="RUNPROG"/ARGUMENTS®"X Y Z" 

DclIefelUn r f thlS GXampIe creates a command symbol RUNPROG (at 
Cij level) to run an image named MYPROO FYTT i ^ 

debugger. The debater RTTN J u• The Second lme starts the 

_ j j u KUN command then brings the imae’e MYPROr 1 t?yt? 

under debugger control Thp /POMMAMn g ivirrKULr.hXE 

—- 

3. DBG> RUN/ARGUMENTS= "X Y Z" MYPROG 

XasTfte a^fments xTr ^ “"<>er debugger control 
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SAVE 


SAVE 


Preserves 


the contents of an existing screen display in a new display. 


Note 


is command is not available in the DECwindows Motif interface to the 


This 
debugger. 


Format 


SAVE old-display AS new-display [>■••] 


Parameters 


Qualifiers 


^£1 display whose contents are saved. You can specify any of the 

following entities: 

• A predefined display: 

SRC 

OUT 

PROMPT 

INST 

REG (VAX only) 

. A display previously created with the DISPLAY command 

• A display built-in symbol: 

%CURDISP 

%CURSCROLL 

%NEXTDISP 

%NEXTINST 

%NEXTOUTPUT 

%NEXTSCROLL 

%NEXTSOURCE 

name of the new display to be seated. This new display then 
receives the contents of the old-disp display. 

sumx denote8 

the visible process at the time the command was issued. 
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SAVE 


Use any of the following process-identifier-type keywords: 


PROCESS.NAME 
PROCESS_NUMBER 

PROCESS.PID 


Description 


The display-name suffix is the process name 

£ &£” P tr ni,mbpr (as 

n™SpiDT me ^ ^ ^ Pr0CeS3 

idwitifier^ype^used^for the^display^nami? keyw ° rd ’ lh « Process 
used for the prompt suffix (see the SET PROMTOSOTPK^aX “ 

“a Zl L S T h r “ Py ° f “ d ^ay 

text contents asffie exS^ ^ ffi" "Tra/tfne T*? the ““ 
attributes or characteristics of the old display except S ** *7? aU the 

screen and is never automatically undated v ep ,^ at 111S removed from the 

to the terminal screen with the DISPLAY command. ^ ^ SaVed display 

routine (by scrolling thelaved dMay) m8trUCt " > " S ass '* i “ ted *«> 

You cannot save the PROMPT display. 

Related commands: 

DISPLAY 

EXITLOOP 


Example 


DBG> SAVE REG AS OLDREG 


This command saves the contents of the 
created display named OLDREG. ♦ 


display named REG into the newly 
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SCROLL 


SCROLL 


Scrolls a screen display to 
window. 


make other parts of the text visible through the display 


Note 


This command is not 
debugger. 


available in the DECwindows Motif interface to the 


Format 


SCROLL [display-name] 


Parameters 


S3ET3U be s "° Ued ' You can Bpeclfy any ot the f “ ent “ es: 

• A predefined display: 

SRC 

OUT 

PROMPT 

INST 

REG (VAX only) 

. A display previously created with the DISPLAY command 

• A display built-in symbol: 

%CURDISP 

%CURSCROLL 

%NEXTDISP 

%NEXTINST 

%NEXTOUTPUT 

%NEXTSCROLL 

%NEXTSOURCE 

If you do not specify a display, the current scrolling display, as established by e 
SELECT command, is chosen. 


Qualifiers 


/BOTTOM 

Scrolls down to the bottom of the displays text. 

/DOWN:[n] , .. es to rev eal text further down in the 

S”r^l"tay is by approximately 3/4 of its window 

height. 

scrolled left by 8 columns. 
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SCROLL 


Description 


Examples 


/RIGHT[:n] 

w^nr) lls n K ght , 0ve ^ the dls P la y’s text by n columns to reveal text beyond the right 

/SUFFIX[=process-identifier-type] 

^l^v^fue'MULTIPROCI^Scn^A^ 116 / 011 ^ 8111 ^ 3 ^ 011 <when D BG$PROCESS has 
ae MULIIPROCESS). Appends a process-identifying suffix to a di«nl*v 

333J£,Sr2£ S, t ect,y afto 7 dispIay — ““ 

vibioie process at the time the command was issued. 

I«n/ SU f fl IX ^ Ualifie y is USed P rimaril y in command procedures when you snecifv 
display definitions or key definitions that are bound to display demons ? fy 

Use any of the following process-identifier-type keywords: 


PROCESS_NAME 
PROCESS_NUMBER 

PROCESS_PID 


The display-name suffix is the process name. 

The S* SUffix ! S the P rocess number (as shown 
m a SHOW PROCESS display). 

The display-name suffix is the process identification 
number (PID). 

If you specify /SUFFIX without a process-identifier-type keyword the process 
identifier type used for the display-name suffix is, by default, the same as that 
used for the prompt suffix (see the SET PROMPT/SUFFIX command). 

/TOP 

Scrolls up to the top of the display’s text. 

/UP[:n] 

j-™! ls up over the ^splay’s text by n lines to reveal text further up in the 
height y ° U ° mit U ’ the dlSplay is scroIled by approximately 3/4 of its window 


The SCROLL command moves a display up, down, right, or left relative to its 
window. S ° Van ° US PartS ° f the diSplay t6Xt Can be made visibl e through the 

Use the SELECT/SCROLL command to select the target display for the SCROLL 
command (the current scrolling display). y otKOLL 

For a list of the key definitions associated with the SCROLL command see 

Keypad Defimtions_CI help topic. Also, use the SHOW KEY command to 
determine the current key definitions. command to 

Related command: SELECT. 


1. DBG> SCROLL/LEFT 

This command scrolls the current scrolling display to the left by 8 columns. 

2. DBG> SCROLL/UP: 4 ALPHA 

This command scrolls display ALPHA 4 lines up. 
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SEARCH 

Searches the source code for a specified string and displays source lines that 
contain an occurrence of the string. 


Format 

SEARCH [range] [string] 


Parameters 


range 

Specifies a program region to 
mod-name 


be searched. Use any of the following formats: 

Searches the specified module from line 0 to the 
end of the module. 


mod-name\line-num 
mod-name\line-num:line-num 


Searches the specified module from the specified 
line number to the end of the module. 

Searches the specified module from the line 
number specified on the left of the colon to the 
line number specified on the right. 


line-num 


line-num:line-num 


null (no entry) 


Uses the current scope to find a module and 
searches that module from the specified line 
number to the end of the module. The current 
scope is established by a previous SET SCOPE 
command, or the PC scope if you did not enter 
a SET SCOPE command. If you specify a scope 
search list with the SET SCOPE command, the 
debugger searches only the module associated 
with the first named scope. 

Uses the current scope to find a module and 
searches that module from the line number 
specified on the left of the colon to the line 
number specified on the right. The current 
scope is established by a previous SET SCOPE 
command, or the PC scope if you did not enter 
a SET SCOPE command. If you specify a scope 
search list with the SET SCOPE command, the 
debugger searches only the module associated 
with the first named scope. 

Searches the same module as that from which 
a source line was most recently displayed (as 
a result of a TYPE, EXAMINE/SOURCE, or 
SEARCH command, for example), beginning at 
the first line following the line most recently 
displayed and continuing to the end of the 


module. 


Specifies the source code characters for which to search. If you do not specify a 
sSng, the string specified in the last SEARCH command, if any, is used. 
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SEARCH 


Qualifiers 


TnS™ S ‘ ring in qU °“ 0n markS <" * OT strophes (■) under the 

The stnng has any leading or ending space or tab characters 

• The string contains an embedded semicolon 

• The range parameter is null 

L*V“7to1nTcL°t S e d in T at J° n mark8 ’ use tw ° consec utive quotation 

• ; } *° indlcate ^ enclosed quotation mark. If the string is enclosed 

”poZphe P ’ USe tW ° C ° nSeC,ltiVe (") to indicated SdoS 


/ALL 

/IDENTIFIER 

/NEXT 

m thT"" 1 ?| e ? Uies thal the debugger search for the next occurrence of the strinn 
m the spec,fled range and display only the line containing this ZT n ” 8 

/STRING 

S P ecif ! es that the debugger search for and display the string as 
specified, and not interpret the context surrounding an occurrence n f +if 0 + • 
as it does in the case of /IDENTIFIER. occurrence of the string, 


Description 


The SEARCH command displays the lines of source code that contain an 
occurrence of a specified string. contain an 

«t y °Th S dS!l,1n m0d Kl name ™ th the SEAECH that module must be 

me W ^ e ^ er a particular module is set, use the SHOW MODTTT F 
command, then use the SET MODULE command, if necessmT 

f‘ h *n SBAI,CH “ mmand determine » heth “ ft* debugger- 
/^XT) a?d ^2) disT" 6 " 068 </ALL) ° f the String ° r next occurrence 

canhc, 6 ""rt if ^ character'that 

be part of an identifier in the current language (/IDENTIFIER). 

IT,-?SelTsET 86 sITr™^” “T" andS with 4116 same O^Aer, y°u 

(for example £®T SeIr™ ^ .“"T /“ eStaMi8h 3 neW default Aoalifler 

SEAECBS.L) The^ ? ALL makes the SEARCH command behave like 
* ^ en y° u n °t have to use that qualifier with the SFAFPR 

the C T ent defau “ Aflers fo“reta of a 

single SEARCH command by specifying other qualifiers. 

Related commands: 

(SET,SHOW) LANGUAGE 
(SET,SHOW) MODULE 
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SEARCH 


Examples 


(SET,SHOW) SCOPE 
(SET,SHOW) SEARCH 


DBG> SEARCH/STRING/ALL 40:50 D 


40: 

02 

D2N 

41: 

02 

D 

42: 

02 

DN 

47: 

02 

DR0 

48: 

02 

DR5 

49: 

02 

DR10 

50: 

02 

DR15 


COMP-2 VALUE -234560000000. 
COMP-2 VALUE 222222.33. 
COMP-2 VALUE -222222.333333. 
0 . 1 . 


COMP-2 VALUE 
COMP-2 VALUE 
COMP-2 VALUE 
COMP-2 VALUE 


0 . 000001 . 

0 . 00000000001 . 

0 . 0000000000000001 . 


DBG> 

This command searches for all occurrences of the letter D in lines 40 to 50 of 
the module COBOLTEST, the module that is in the current scope. 

DBG> SEARCH/IDENTIFIER/ ALL 40:50 D 

module COBOLTEST T7 „ TTTE . 009099 is 

41 . 02 D COMP-2 VALUE 222222.33. 

DBG> 

This command searches for all occurrences of the letter D in lines 40 to 50 
of the module COBOLTEST. The debugger displays the only line where 
letter D (the search string) is not bounded on either side by a character that 
can be part of an identifier in the current language. 

DBG> SEARCH/NEXT 40:50 D 

m ° dU 40: C 02° LTEST D2N COMP-2 VALUE -234560000000. 

DBG> 

This command searches for the next occurrence of the letter D in lines 40 to 
50 of the module COBOLTEST. 


COMP-2 VALUE 222222.33. 


4 DBG> SEARCH/NEXT 
module COBOLTEST 
41: 02 D 

DBG> 

This command searches for the next occurrence of the letter D. The debugger 
assumes* IM;o be the search string because D was the last one entered and no 
other search string was specified. 


COMP-2 VALUE 0.1. 


DBG> SEARCH 43 D 
module COBOLTEST 
47: 02 DR0 

DBG> 

This command searches for the next occurrence (by default) of the letter D, 
starting with line 43. 
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SELECT 


iSP ' ay 83 ^ C , Urren ‘ em,r ’ ta P“‘. ^truction, output, 
prompt, scrolling, or source display. p 


program, 


Note 


debugg“ ma " d 18 ” 0t aVailaMe ” thC DEC ™ d °»s Motif interface 


to the 


Format 


Parameters 


SELECT [display-name] 


Qualifiers 


display-name 

t *■»-*« -th 

• A predefined display: 

SRC 

OUT 

PROMPT 

INST 

REG (VAX only) 

A display previously created with the DISPLAY command 

• A display built-in symbol: 

%CURDISP 

%CURSCROLL 

%NEXTDISP 

%NEXTINST 

%NEXTOUTPUT 

%NEXTSCROLL 

%NEXTSOURCE 

If you omit this parameter and do not specify a qualifier you "unselect- th« 

^Tthi, g , di8P K lay <n ° diSplay then has the filing attribute) If ™u 

unseiect the current display wfth It attriS ^Sr^SnT 

/ERROR 

Selects the specified display as the current error display This causes all 

& rd S^ 

selects thp Prompt A' i ^ ^you do not specify a display 

t™™ *Sbute current OTar display By defauit -*• 
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SELECT 


S the specified display as the current $£ 

display to echo debugger input (which appears in the PROMPT display;. 

display specified must be an output display. 

PROMPT display). By default, no display has the input attribute, 
display specified must be an instruction display. 

If you do not specify a display, the current instruction display is unselected and 
no display has the instruction attribute. 

By default, far all languages 

attribute. If the language is set to MACKU-cSZ, tne unoi u p y 
instruction attribute by default. 

dS The display specified must be either an output drsplay or the PROMPT 
display. 

the PROMPT display can be specified. 

If you do not specify a display, the current program dispiay is unselected and 
program input and output are no longer forced to the specified display. 

By default, the PROMPT display has the program attribute, except on 
workstations, where the program attribute is unselected. 

SelertTthe specified display as the current Prompt^sp^ This us where 

the debugger prompts for input. Ourrentl^ ony display (the PROMPT 

specified. Moreover, you cannot unselect the PROMP1 display ttne 

display always has the prompt attribute). 

dTlnot thrsCROll"—“‘S the PROMPT display. 

If you do not specify a display, the current scrolling display is unselected and no 
display has the scroll attribute. 

By default, for all languages -“P^R^S £& £ £ ^ 
attribute. If the language is set to MACRO-oA tne inoi »u**F y 

attribute by default. 
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SELECT 


/SOURCE 

This causes *■» 

display specified must be 7ZZ^™ C ° mmandS *” g ° “> that ”» 

SaylTtheTut: attribute. 116 Cm ' r6nt ^ diS » lay is unsaI ^ “d no 

Sibute^Tb! 1 ! langua « es ex “P‘ MACRO-32, the SRC display has the source 
attribute by def:iu ngUa8e ,S "* 10 “C* 0 " 32 ’ a ° "*** »as the source “ 

/SUFFIX[=process-identifier-type] 

the^value°MUI^IPROC^SS^ A^ 11 ^ 011 ^^ 111 ^ 3 ^ 011 (when DBG $ PRG CESS has 

KsSSSSr-a 

i^assasasac- 

Use any of the following process-identifier-type keywords: 


PROCESS_NAME 
PROCESS_NUMBER 

PROCESS_PID 


The display-name suffix is the process name. 

The display-name suffix is the process number (as shown 
m a SHOW PROCESS display). 

The display-name suffix is the process identification 
number (PID). 


Description 


thed 0 "', 6 byword, the proceas 

uemmer type used tor the display-name suffix is, by default the samp «» tw 

used for the prompt suffix (see the SET PROMPT/SUFFIX command). 


^^K^ofdebi^^^output't^particular'display^This^^esyoirt^^tion'of 118 

as d —~ ^ 

Slr^ 

it you do not specify a qualifier, /SCROLL is assumed y y aeIault > 

informative ft“iuT» 6 a " 0ther SELECT “ mma “ d - k"or more 

determine the current key definitions. command to 

Related commands: 


DISPLAY 

EXPAND 

MOVE 

SCROLL 
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SELECT 


Examples 


SHOW SELECT 


DBG> SELECT/SOURCE/SCROLL SRC2 

This command selects display SRC2 as the current source and scrolling 
display. 

DBG> SELECT/INPUT/ERROR OUT 

This command selects display OUT as the current input di ^ nt 

This causes debugger input, debugger output (assumi g 0OT 

output display), and debugger diagnostrc messages to be logged m the UU1 

display in the correct sequence. 

dbg> select/source 

command then goes to the currently selected output display. 
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SET ABORT KEY 


Assigns the debugger’s abort function to another Ctrl-key 
Ctrl/C does the abort function. 


sequence. By default, 


Note 


2~ d iS n0t available “ DECwindows Motif interface 


to the 


Format 


Parameters 


SET ABORTKEY = CTRL_character 

character 

alphabetic'diaracter’ Pr6SS WW ' e h ° Wing d ° Wn the C « 


can specify any 


Description 


Example 


ss with ; n a ***** 

SET ABORT KFY ™ d and interru P ts program execution. The 

Strl-lTsewST X Zht n h y ° U *° a f ign 4116 ab ° rt functi0n to a "°‘ b «' 

service routine enabled ' t, ° m pr0gram has a CWC AST 

Many Ctrl-key sequences have predefined functions, and the SET ABORT KEY 
command enables you to override such definitions ( ee the OpenVm Sf* 

“ an^T ° f ‘ he CW - key “ rS “* b * ‘ ba °P-fi“m are 

2-S™SL”""” d iden “ eS the “**" a « currently in 

or°ar^equh'Ment^Ctrl’k Wltbm a debu Sging session. Instead, use either Ctrl/C 
command ^ Ct 1_key sequence established with the SET ABORT_KEY 

Related commands: 

Ctrl/C 

Ctrl/Y 

SHOW ABORT_KEY 


DBG> SHOW ABORT KEY 
Abort Command Key is CTRL C 
DBG> GO 
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SET ABORT_KEY 


DBG>11mINE/BYTE 1000:101000 ! should have typed 1000:1010 

1000 : 0 
1004: 0 
1008: 0 
1012: 0 
1016: 0 

%DEBWFw-ABORTED, command aborted by user request 
DBG> SET ABORT_KEY = CTRL_P 
DBG> GO 

DBG>^IIamINE/BYTE 1000:101000 !should have typed 1000:1010 

1000: 0 
1004: 0 
1008: 0 
1012: 0 
1016: 0 

%DEBUG-W-ABORTED , command aborted by user request 
DBG> 

This example shows the following: 

• Use of Ctrl/C for the abort function (default). 

. Use of the SET ABORT_KEY command to reassign the abort function to 
Ctrl/P. 
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SET ATSIGN 


SETATSIGN 


Format 


Parameters 


6 8peciflcati<m that tha d ^ 8 er uses when searching 


SET ATSIGN file-spec 


file-spec 

fvntww*!? 0f a file s P ecifi cation (for example, a directory name or a file 
type) that the debugger is to use by default when searching for a command 

SYS$mSK nDFRT^ n rnM PPly u a M1 ^ s P ecification . the debugger assumes 
SYS$DISK.t JDEBUG.COM as the default file specification for any missing” eld. 

You can specify a logical name that translates to a search list. In this case the 
debugger processes the file specifications in the order they appear in the search 
list until the command procedure is found. 


Description 


Example 


cOTnmarid 1 STSk® debugger comiaand Procedure with the execute procedure (@) 
command, the debugger assumes, by default, that the command procedure file 

yrf^eSeS® EBU&COM ' The SET ATSIGN “ mma ” d “ aH <* 

Related commands: 

@ (Execute Procedure) 

SHOW ATSIGN 


DBG> SET ATSIGN USER:[JONES.DEBUG].DBG 
DBG> @TEST 

fte debugger loaks f " the 
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SET BREAK 


SET BREAK 


Establishes a breakpoint at the location denoted by an address expression, at 
fns^tions of a particular class, or at the occurrence of specified events. 


Format 


SET BREAK [address-expression[, ... ]] 

[WHEN(conditional-expression)] 
[DO(command[; ...])] 


Parameters 


Specffie* an address expression (a program location) at which a breakpoint is 
to be set With high-level languages, this is typically a line number, a routi 
name or a label and can include a path name to specify the entity uniquely. 

More generally an address expression can also be a memory address or a regis er 
SXtacSpoeed of numbers (offsets) and symbols, as well as one or more 
operators operands, or delimiters. For information about the operators that y 
can use in address expressions, see the Address.Expressions help topic. 

Do not specify the asterisk (*) wildcard character. Do not specify an address 
expression with any of the following qualifiers: 

/ACTIVATING 

/BRANCH 

/CALL 

/EXCEPTION 

/INSTRUCTION 

/INSTRUCTION=(opco<2e[, . . . ]) (VAX only) 

/INTO 

/[NO]JSB (VAX only) 

/LINE 

/OVER 

/[NOISHARE 

/[NO]SYSTEM 

/TERMINATING 

/UNALIGNED_DATA (Alpha systems only) 

/VECTORJNSTRUCTION (VAX only) 

The /MODIFY and /RETURN qualifiers are used with specific kinds of address 
expressions. 

If vou specify a memory address or an address expression whose value is not 
a symbolic location, check (with the EXAMINE command) that an instruction 
actually begins at the byte of memory so indicated. If an instruction does 
, . , ,1 ■ h t „ mn .time error can occur when an instruction including tha 

byteis executed. When you set a breakpoint by specifying an address expression 
those value is not a symbolic location, the debugger does not verify that the 
location specified marks the beginning of an instruction. 
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SET BREAK 


On VAX systems, CALLS and CALLG rontines start with an entry mask. . 

conditional-expression 

Specifies a conditional expression in the currently set language that is to he 
evaiuated whenever execution reaches the breakpoint. (The debugger checks 
the syntax of the expressions in the WHEN clause when execution reaches 
the breakpoint, not when the breakpoint is set.) If the expression is true the 
ebugger reports that a breakpoint has been triggered If an action mo cl i 
.s assodated with the breakpoint, it will occur aStil " fTe 

spedliedTarfnot n0t ‘T?’ “if commands specified by the DO clause .if one was 
specified) are not executed, and program execution is continued. 

command 

b?eafa e L a ontS e o”Th m !; n K 40 be ^ ° f the D0 clause when 

Z.e .. tak The debugger checks the syntax of the commands in a DO 
clause when ,t executes the DO clause, not when the breakpoint is set 


Qualifiers 


/ACTIVATING 

Applies to a multiprocess debugging configuration (when DBGSPROCESS 
has the value MULTIPROCESS). Causes the debugger to break wheS a L 
process comes under debugger control. The debugjfr prompts dlplayed win 
the first process comes under debugger control. This enables you to enter 

frEMNl™G n q ua“r re ‘ h '’ Pr0gram haS ***** eXeCUtl0n - als “ «*> 

/AFTER.n 

Specifies that break action not be taken until the nth time the designated 
breakpoint is encountered (n is a decimal integer). Thereafter, the breakpoint 

(ifTnprwTrn im< h ^ 1S aacountered Provided that conditions in the WHEN clause 
as SET BReIS. ^ BREAK/AFTE R^ command has the same effect 

/BRANCH 

Causes the debugger to break on every branch instruction encountered during 
program execution. See also the /INTO and /OVER qualifiers g 

/CALL 

Causes the debugger to break on every call instruction encountered durine 

” q u e ssr g the eet instmot, ° n ' sce ais ° ^ ®>ro a °d 

/EVENT=event-name 

debugger to break on the specified event (if that event is defined and 

/EVENT ca G 'r" 1 faClllty) ' If y° u specify an address expression with 
^NT, causes the debugger to break whenever the specified event occurs for 

event names. eXPreSS1 ° n ' Y °“ Cami0t SP6dfy 3n address session with certain 

^rt n Lt C DECthre r aH aVailable f °^ T pr °f ams that cal1 Ada «r SCAN routines or 
tnat use UECthreads services. Use the SHOW EVENT FACTT TTY l 

■dentify the current event facility and the a S sociated^„fname7 * 
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SET BREAK 


Alpha 




(SSes^he debugger to break whenever an exception is signaled. The break 
SZcS™ before any application-declared exception handlers are invoked. 

As a result of a SET BREAK/EXCEPTION command, whenever your program 
generates an exception, the debugger suspends program execution, reports 
the exception, and displays its prompt. When you resume execution 
exception breakpoint, the behavior is as follows: 

. If you enter a GO command without an address-expression Parameter the 
exception is resignaled, thus allowing any application-declared exception 
handler to execute. 

• If you enter a GO command with an address-expression parameter, program 
exec" ion continues at the specified location, thus inhibiting the execution of 
any application-declared exception handler. 

• If vou enter a STEP command, the debugger steps into any aPP 110 ^ 1011 - 
decl^ed exception handler. If there is no application-declared handler for 
that exception, the debugger resignals the exception. 

. If you enter a CALL command, the routine specified is executed. ^ a routme 
is called with the CALL command directly after an exception breakpoint 
been^triggered, no breakpoints, tracepoints, or 

routine are triggered. However, they are triggered if the CALL command 
given at another time. 

On Alpha processors, an exception might not be delivered (to the program or 
debugger) immediately after the execution of the instruction that caused th 
exception. Therefore, the debugger might suspend execution on an instruction 
beyond the one whose execution actually caused the exception. 

Wlmn^you^do not^ specifj^an opcode, causes the debugger to break on every 
instruction encountered during program execution. 

On VAX processors only, you can optionally specify one or more * opcodes. This 
causes the debugger to break on every instruction whose opcode is in the list. 

If you specify a vector instruction, do not include an instruction qualifier (/U, /V, 
/M, /0, or /l) with the instruction mnemonic. ♦ 

See also the /INTO and /OVER qualifiers. 

(Default.) Applies only to breakpoints set with the following qualifiers (that is, 
when an address expression is not explicitly specified): 

/BRANCH 

/CALL 

/INSTRUCTION 

/INSTRUCTION=(opcode[, . . . ]) (VAX only) 

/LINE 

/VECTOR_INSTRUCTION (VAX only) 

When used with those qualifiers, /INTO causes the debugger to break at the 

specified points within called routines (as well as within the 

execution is currently suspended). The /INTO qualifier is the default and the 

opposite of /OVER. 
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SET BREAK 




woSSSm" quaUfy the break action -‘ h «°wsb, 


/JSB 

/NOJSB 


OnWXprocessors, qualifies /INTO. Use with /INTO and one of the following 

/BRANCH 

/CALL 

/INSTRUCTION 
/INSTRUCTION=(opcorfe[, ]) 

/LINE 

/vectorjnstruction 

debujSr b^ftta^uStat arecaltod by the" JSB D1B £at !** 

The /NOJSB qua liber (ft. DimSSS^I^ 

routines'"^ ralTed by fte CAL^ m . Stm . Ctions J [ " DIB °L, appbcation-declared 
are calTedTyftelsB .£££??*“ “ 4 DIB ° L "»«“ T routines 

/LINE 

Causes the debugger to break on the beginning of each source line encountered 
ng program execution. See also the /INTO and /OVER qualifiers. 

/MODIFY 

S 0 S p™uS'fte I s7n, C e“SS" eXaCt ‘ y * SET WATCH “ mm “ d 

default length to 2 bytes) or BTT^SCT tS whSb K S fu 
length to 1 byte,. SET TYPE LONflwa 4 *2! 

/OVER 

Applies only to breakpoints set with the following qualifiers (that is whan an 
address expression is not explicitly specified): ’ “ 

/BRANCH 

/CALL 

/INSTRUCTION 

/INSTRUCTION=(opcoc/e[, . . . ]) (VAX only) 

/LINE 

/VECTORJNSTRUCTION (VAX only) 

When used with those qualifiers, /OVER causes the debugger to break at tha 

(MtwhhfnSleTLtiies" The" /OVER eXG ™ tion is currently suspended 

is the default). /0VER qUahfier 18 the °PP° site of/INTO (which 
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Alpha 


SSS2SS” 

your architecture. 

On VAX processors, this qualifier can only be applied t..routinescalled with a 
CALLS or CALLG instruction; it cannot be used with JSB routine . 

On Alpha processors, this qualifier can be applied to any routine. 

A SET BREAK/RETURN command cancels a previous SET BREAK if you specify 
the same address expression. 

/SHARE (default) 

Quahfies^/INTO. Use with /INTO and one of the following qualifiers: 

/BRANCH 

/CALL 

/INSTRUCTION 

/INSTRUCTION=(opcode[, ... 1) (VAX only) 

/LINE 

/VECTORJNSTRUCTION (VAX only) 

The /SHARE qualifier permits the debugger to break within shareable image 
roSinesV well as other routines. The /NOSHAKE qualifier specifies that 
breakpoints not be set within shareable images. 

/SILENT 

oSSZSSZ -break ... - ~ £££££* 

location are delayed at the^br«ik^oint. The MC ’ the meBsage and 

£ Sn: rSpla; "s?LENT qualifier overrides /SOURCE. See 
also the SET STEP [NO]SOURCE command. 

/SOURCE (default) 

command. 

/SYSTEM (default) 

Quahfies /INTO. Use with /INTO and one of the following qualifiers: 

/BRANCH 

/CALL 

/INSTRUCTION 
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SET BREAK 


Alpha 


Description 


S RUCTION=( ^ co ^, • • • J) (VAX only) 

/LINE 

/VECTOR_INSTRUCTION (VAX only) 

/TEMPORARY 

reZS pe™r n t% n sett diSaPP<iar afler “ 18 triggered (the break P““t d °- 

/TERMINATING 

Causes the debugger to break when a process does an imaee exit Th* ^ 
orm S ir 11 ^ 1 30(1 displayS its when the last imag/of a one-proces^^ 

ZZedTe' 6Xi ‘ S ' A Pr0C r iS terminateli » h “ ImagThas 
also the /lcTTOTmC“ e ’**' ““ hand,erS haTC '»“* a ‘ ad ' *• 

/UNALIGNED_DATA 

/VECTOR_INSTRUCTION 

On VAX processors, causes the debugger to break on every vector instruction 
, ° untered dunn g Program execution. See also the /INTO and /OVER qualifiers. 


When a breakpoint is triggered, the debugger takes the following actions: 

1. Suspends program execution at the breakpoint location. 

count* Tithete^ T f Wh K n T S6t the breakpoint ’ «*«*■ the AFTER 
count. If the specified number of counts has not been reached execution 

resumes and the debugger does not do the remaining steps 

®7'“ a ^‘ *7 ^PMfsion in a WHEN clause, if you specified one when you 

and fte d e b ‘’‘""a If the Va ‘ Ue ° f ^ eK Pression is false, execution resumes 
and the debugger does not do the remaining steps. resumes 

^ ir 6 " 1 h T reaChed * he breakpoint Nation by issuing a 
Dreak . . . message, unless you specified /SILENT. 

Verified ^OSOURrT r 7nnt^ Wh / Ch is suspended, unless you 

previously entered SET STEP NOSOURCE° U ““ breakpoint ° r “ ntess 

breSto e ifTe"S d V n “ D0 C ‘ aUSe ' ify °“ spedfied °" a "hen ‘he 

Issues the prompt. 


2 . 


3. 


4 . 
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SET BREAK 


Alpha 


You set a breakpoint at a particular location in your program by specifying ^ 
You set a preaKpomt f rreak command. You set a breakpoint on 

The /LINE qualifier sets a breakpoint on each line of source code. 

The following qualifiers set breakpoints on classes of instructions. Using these 
causes the debugger to trace every instruct™ of your 
program as it executes and thus significantly slows down execution. 


/BRANCH 

/CALL 

/INSTRUCTION 

/INSTRUCTION=(opcode[, . . . ]) (VAX only; 

/return 

/VECTOR_INSTRUCTION (VAX only) 

The following qualifiers set breakpoints on classes of events: 

/ACTIVATING 

fEVENT=event-name 

/EXCEPTION 

/TERMINATING 

/UNALIGNED_DATA (Alpha only) 

The following qualifiers affect what happens at a routine call: 


/INTO 

/[NO]JSB (VAX only) 

/OVER 

/[NOISHARE 

/[NOISYSTEM 

The following qualifiers affect what output is displayed when a breakpoint is 

reached: 

/[NOISILENT 

/[NOISOURCE 

The following qualifiers affect the timing and duration of breakpoints: 

/AFTER:n 

/TEMPORARY 

Use the /MODIFY qualifier to monitor changes at program locations (typically 
changes in the values of variables). 

If you set a breakpoint at a location currently used as a tracepoint, the tracepoint 
is canceled in favor of the breakpoint, and vice versa. 

program call fails. If the program call occurs before you .ssue 
the command, unaligned breaks are not set. ♦ 
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SET BREAK 


Examples 


Related commands: 


(ACTIVATE,DEACTIVATE) BREAK 
CANCEL ALL 
GO 

(SET,SHOW) EVENT_FACILITY 
SET STEP [NOJSOURCE 
SET TRACE 
SET WATCH 

(SHOW,CANCEL) BREAK 
STEP 


1. DBG> SET BREAK SWAP\%LINE 12 

This command causes the debugger to break on line 12 of module SWAP. 

2. DBG> SET BREAK/AFTER:3 SUB2 

times^^Tsi^^l^routin^i^^^cuted! 1 ^ 6 ^ “ 

3. DBG> SET BREAK/NOSOURCE L00P1 DO (EXAMINE D; STEP; EXAMINE Y; GO) 

This command causes the debugger to break at location LOOP1 At 

breakS "" SUPPr6SSeS the displa y of source code at the 

4. DBG> SET BREAK ROUT3 WHEN (X > 4) DO (EXAMINE Y) 

break on routine R0UT3 when 
• th 4 ' At the breakpoint, the EXAMINE Y command id 

;r^:rr. of fte —-*. w£ E “ s i8 

'• DBG > SET BREAK/TEMPORARY 1440 
DBG> SHOW BREAK 
breakpoint at 1440 [temporary] 

DBG> 

s at mem °^ addre - id «- ** 
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6 DBG> SET BREAK/LINE 

This command causes the debugger to break on the beginning of ever, source 
line encountered during program execution. 


7 DBG> SET BREAK/LINE WHEN (X .NE. 0) 

DBG> SET BREAK/INSTRUCTION WHEN (X .NE. 


0 ) 


These two commands cause the debugger to break when X is not equal to 0. 
S!^command tests for the condition at the beginnmg of every source lme 
encountered during execution. The second command testo for the conditio 
attach instruction! The syntax of the conditional express,on m the WHEN 
clause is language-dependent. 

g DBG> SET BREAK/INSTRUCTI0N=ADDL3 

This command causes the debugger to break whenever the instruction ADDL3 
is about to be executed. ♦ 

9 dbg> set break/line/into/noshare/nosystem 

This command causes the debugger to break on the beginning of every source 
line, including lines in called routines <™TO) but not m shareable image 
routines (/NOSHARE) or system routines (/NOSYSIEM). 

10. DBG> SET BREAK/RETURN ROUT4 

This command causes the debugger to break whenever the return instruction 
of routine ROUT4 is about to be executed. 

11 . DBG> SET BREAK/RETURN %LINE 14 

This command causes the debugger to break whenever the ^tni C tion 

of the routine that includes line 14 is about to be executed^ This form ot the 
command is useful if execution is currently suspended within a routine and 
you want to set a breakpoint on that routines return instruction. 

DBG> SET BREAK/EXCEPTION DO (SET MODULE/CALLS; SHOW CALLS) 

commands are issued. 

13 . DBG> SET BREAK/EVENT=RUN RESERVE, %TASK 3 

This command sets two breakpoints, which are associated ^th task 

RESERVE and task 3 (task ID = 3), resp,actively. 1 Each breakpoint trigg 

whenever its associated task makes a transition to the RUN state. 

14 . DBG_1> SET BREAK/ACTIVATING 

This command causes the debugger to break whenever a process of a 
multiprocess program is brought under debugger control. 


12 . 
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SET DEFINE 


Format 


Parameters 


° 0MMAND - pr °CESS_GROUP, or 


SET DEFINE define-default 


define-default 

Specifies the default 
(which correspond to 

ADDRESS 

COMMAND 

PROCESS_GROUP 

VALUE 


‘dfJinf b “ Shed *T the , DEFINE ““““d- Valid keywords 
DEFINE command qualifiers) are as follows: 

Subsequent DEFINE commands are treated as 
DEFINE/ADDRESS. This is the default. 

Subsequent DEFINE commands are treated as 
DEFINE/COMMAND. 

DEFSROCEs“GRSu“ dS tr<iated “ 
DEFm^l?UE INE C ° mmand8 are trcated as 


Description 


Example 


DEFI S NE c^m FINE /°T^ and establishes a def ault qualifier for subsequent 

rr, d fl ^ 

binds a —“ 

°™ nide ?k CUrren ) DEFINE default for duration of a single 

EFINE command by specifying another qualifier. Use the SHOW DEFINF 
command to identify the current DEFINE defaults. INE 

Related commands: 

DEFINE 

DEFINE/PROCESS.GROUP 

DELETE 

SHOW DEFINE 

SHOW SYMBOL/DEFINED 


DBG> SET DEFINE VALUE 

The SET DEFINE VALUE command specifies that subsequent DEFINE 
commands are treated as DEFINE/VALUE q 1NE 
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SET EDITOR 

Establishes the editor that is started by the EDIT command. 


Format 


SET EDITOR [command-line] 


Parameters 


Qualifiers 


“Sfatlmand line to start a particular editor on your system when you 
use the EDIT command. 

specified in the SET EDITOR command line is spawned to a subprocess w en you 
enter the EDIT command. 

You can specify a command line with /CALLABLBLLSEDIT or /CALLABLE.TPU 
but not with /CALLABLE_EDT. 


sESJFsssn 

line of "EDT" is used). 

/CALLABLE_LSEDIT 

“ “ —d line, it is passed to .caUable l^EDIT. If you do not specify 
a command line, the default command line is LSED1I. ♦ 

It is passed to callable DECTPU. If you do not specify a command lme, the default 
command line is TPU. 

/START_POSITION 

- tp5 ° r , 

^CALLABLETPlh and LSEDIT or /CALLABLE.LSEDIT, respectively) support 
this qualifier. 

The «TART.POSm„«era|ech.the ^";^a«d”t the 

.me 

^sW^SmOrle"^ either on the line whose 
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SET EDITOR 


Description 






Alpha 


Examples 


o^yo^ T s ™™f n ~? d th naWeS yt,U ,*? afeafy -V ““to ttat is installed 

™ss^ - - set 

On VAX processors, if you use EDT LSEDTT nr n^PTOTT 

LSEDIT n or /CALlSl^TPU ^ h” Speci \ /CALLAB LSDT n /CALLABLE. 
LSEDIT and DFCTPTT _ . which causes the callable versions of EDT, 

SS2 SBC?™* 1,6 i T ked * «>• EDIT command! In 

executed by the clwe ed f" . ' *" “ "" *** a «», * 

n "t "SI^SSwtT ^ /CALLABLE -EI>T -r /CALLABLE_TPU, but 
Related commands: 

EDIT 

(SET,SHOW,CANCEL) SOURCE 
SHOW DEFINE 


1. DBG> SET EDITOR ' @MAIL$EDIT 

’©MAJLSEDTr “T “ mma ”d to spawn the command line 

UMAILSEDIT , which starts the same editor as you use in MAIL. 

2. DBG> SET EDITOR/CALLABLE_TPU 

This command causes the EDIT command to start callable DECTPU with the 
default command line of TPU. Ulfu Wltn tfte 


3. 


DBG> SET EDITOR/CALLABLE_TPU TPU/SECTION=MYSECINI.TPU$SECTION 

This command causes the EDIT command to start callable DECTPU with 

command line TPU/SECTION=MYSECINI.TPU$SECTION 

DBG> SET EDITOR/CALLABLE_EDT/START_POSITION 

Ibis command causes the EDIT command to start callable EDT with the 
default command line of EDT. Also the /START POSTTinu wirn ine 
appended to the command line, so Z 

source Ime that is centered in the debugger’s current sour™ S^Lty 
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SET EVENT_FACILITY 


SET EVENT_FACILITY 


Establishes the current event facility. 

Event facilities are available for programs that call Ada or SCAN routines or that 
use DECthreads services. 


Format 


SET EVENT_FACILITY facility-name 


Parameters 


ADA 


THREADS 


sSesaTevent facility. Valid facility-name keywords are as follows: 

If the event facility is set to ADA, the (SET,CANCEL) BREAK 
and (SET CANCEL) TRACE commands recognize Ada-specific 
events as well as generic, low-level task events. (Ada even s 
consist of task and exception events.) 

You can set the event facility to ADA only if the main program 
is written in Ada or if the program calls an Ada routine. 

If the event facility is set to THREADS, the (SET,CANCEL) 
BREAK and (SET,CANCEL) TRACE commands recognize 
DECthreads-specific as well as generic, low-level task events. 

All DECthreads events are task (thread) events. 

You can set the event facility to THREADS only if the shareable 
image CMA$RTL is currently part of the programs process (if 
that image is listed in a SHOW IMAGE display). 

If the event facility is set to SCAN, the (SET,CANCEL) BREAK 
and (SET,CANCEL) TRACE commands recognize SLAIN 
(pattern-matching) events. 

You can set the event facility to SCAN only if the mam program 
is written in SCAN or if the program calls a SCAN routine. 


fVAX specific 


tSCAN 


Description 


, ~ (AT >» TTTRFAnS or SCAN) defines the eventpoints 

tot”-:"" SET BREAK/EVENT and SET TRACE/EVENT 
commands. 

When started with a program that is linked with an event «ity the debugger 

Je’even? faciiity is 

set to ADA or SCAN, respectively. 

The SET EVENT FACILITY command enables you to change the event facility 

SS^^ran^rCa 

an event facility but that facility is not currently set. 
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SET EVENT_FACILITY 




Example 


the ™e P ZZm’ ^ ^ DEC ‘ hlead> services in 

ADA to SCAN or from DECteaS^ SZSgT ^ 

^rfSSSSSSESScr 

Related commands: 

(SET,CANCEL) BREAK/EVENT 

(SET,CANCEL) TRACE/EVENT 

SHOW BREAK 

SHOW EVENT_FACILITY 

SHOW IMAGE 

SHOW TASK 

SHOW TRACE 


DBG> SET EVENT_FACILITY THREADS 

This command establishes THREADS (DECthreads) as the cnrrent event facility. 
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SET IMAGE 


Loads symbol information for one or more shareable images and establishes the 
current image. 


Format 


SET IMAGE [image-name[, ... ]] 


Parameters 


/ALL. 


Qualifiers 


/ALL 


/MU U 

Specifies that all shareable images are set. 


Description 


The SET IMAGE command builds data structures for one or more specified 
images but does not set any modules within the images specified. 

The "current” image is the current debugging context: you have access to 

SSSSSSSSSSSa' 

the current image is unchanged. 

.mage was linked /NOTRACEBACK, no symbol information is available for t at 
taale and you cannot specify it with the SET IMAGE command. 

grp available for all images. 


Related commands: 

SET MODE [NOIDYNAMIC 
(SET,SHOW,CANCEL) MODULE 
(SHOW,CANCEL) IMAGE 
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SET IMAGE 


Example 


DBG> SET IMAGE SHARE1 
DBG> SET MODULE SUBR 
DBG> SET BREAK SUBR 


module^SURR °f C ° mma J nds . shows how to set a breakpoint on routine SUBR in 
module SUBR of shareable image SHARE 1 The SFT TMAPP ™ ^ , 

debugging context to SHARE 1. The SCT MODULE^ fTT* SetS L the 
records of module SUBR into the run-time s^boHable (RST) BREAK 

command sets a breakpoint on routine SUBR. BREAK 
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SET KEY 

Establishes the current key state. 

_ Note 


This command is not available in the DECwindows Motif interface to the 
debugger. 


Format 

SET KEY 


Qualifiers 


/LOG (default) 

the message. 

/STATE[=state-name] 

Snedfies a key state to be established as the current state. You can specify a 
P 11 , , i pot n nr a user-defined state. A state name can be 

awappropriate 8 Alphanumeric string. The /NOSTATE qualifier leaves the current 
state unchanged. 


Description 


Keypad mode must be enabled (SET MODE KEYPAD) before you can use this 
command. Keypad mode is enabled by default. 

By default, the current hey sta* mthe £ "^ttsign 

you to change the current state to the appropriate state. 

Related commands: 

DELETE/KEY 
DEFINE/KEY 
SHOW KEY 


Example 


dbg> SET KEY/STATE=PR0G3 

This command changes the key state to the PROG3 state. You can now use the 
key definitions that are associated with this state. 
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SET LANGUAGE 


Format 


Establishes the current language. 
SET LANGUAGE language-name 


Parameters 

language-name 

Specifies a language. 

0n VAX processors, valid keywords are: 

ADA BASIC bliss 

C-PLUS_PLUS COBOL DIBOL 

MACRO PASCAL PLI 

SCAN UNKNOWN 


C 

FORTRAN 

RPG 

♦ 


Alpha 


On Alpha processors, valid keywords are: 


ADA 

C 

MACRO 

UNKNOWN 


AMACRO 

C_PLUS_PLUS 

MACR064 


BASIC 

COBOL 

PASCAL 


BLISS 

FORTRAN 

PLI 

♦ 


Description 




Alpha 


™d e uW U f art th ® debugger ’ the current language is set to that in which the 

• «** written tea different 

with the SET LANGUAGE command" Pr0gram ’ you can change the language 
The current language setting determines how the debugger parses and internee 

Sees'- — ns r spedfy ” ’ “a„‘ d “ 

radix for the ente, and ‘S' 1 * 

h ° W ‘ he debUgger and ^P'ay» data 

The default radix for both data entry and display is decimal for most languages 
d°efaufra P dr„7Satim:rr S “ *“* and ^OS2, which have a 

MACRO - 32> and MACR0 ^’ 

tyP ! f0 r pros™™ locations that do not have a compiler-generated 

«,mght o Kp,rc^^^^ 

^ ^ addr6SS ^ USP «» SET ™ 
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SET LANGUAGE 


tt_ 0 tVl „ qFT LANGUAGE UNKNOWN command when debugging a program 
written in an 

including some that might he 

specific to only a few supported languages. 

Note that SET LANGUAGE UNKNOWN can be an easy, quick workaround for 
fan^ie-related problems because it uses the "loosest" set of rules. 

For information about debugger support for language-specific operators and 
constructs, type HELP Language. 

Related commands: 


EVALUATE 

EXAMINE 

DEPOSIT 

SET MODE 

SET RADIX 

SET TYPE 

SHOW LANGUAGE 


Examples 

! DBG> SET LANGUAGE COBOL 

This command establishes COBOL as the current language. 

2 . DBG> SET LANGUAGE PASCAL 

This command establishes Pascal as the current language. 
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SET LOG 


SET LOG 


Format 


Parameters 


ctmmtdhl 1 ? 4116 debUgger Writes after « SET OUTPUT LOG 


SET LOG file-spec 


file-spec 

fneciW* 16 T, ClfiCati ° n ° f the l0g file ‘ If y° u do not supply a full file 
s£eciflc“£m tlwZSSnTS™ SYS * DISR [roEBUG.LOG as the default file 

If you specify a version number and that version of the file already exists thp 

SSTSStat* me me appending log of the "-5SE-L 


Description 


Examples 


The SET LOG command determines only the namp nf a lnrr «i 0 . •+ j 

the debugger to create or write to the specified file. The SET OUITOTLOg ” 86 

command accomplishes that. ‘"eooi uumillOG 

If you entered a SET OUTPUT LOG command but no SET LOG command the 
debugger writes to the file SYS$DISK:[ 1DEBUG.LOG by default. d ' 

SET e i S U c gger iS *? 8 log file and y° u another log file with the 

fflfsp^°"X d SE ft T ^ <* “ d Sto 

Related commands: 

SET OUTPUT LOG 

SET OUTPUT SCREEN.LOG 

SHOW LOG 


1. DBG> SET LOG CALC 
DBG> SET OUTPUT LOG 

£ S^S^cTo^e^^OG 6 “""7 108 “ e 40 

input and debugger output to ta S’SSSif 0 C ° mm8nd “ Ser 

2. DBG> SET LOG [CODEPROJ] FEB29 TMP 
DBG> SET OUTPUT LOG 

£ SSrs de “ g to 

input and debugger output to L logged hTa^le “ Ser 
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SET MARGINS 


SET MARGINS 

Specifies the leftmost and rightmost source-line character position at which to 


begin and end display of a source line. 


Note 


This command is not available in the DECwindows Motif interface to the 
debugger. 


Format 


SET MARGINS 


rm 

lm:rm 

Im: 


Parameters 


Th e source-line character position at which to begin display of the line of source 
code (the left margin). 

Se source-line character position at which to end display of the line of source 
code (the right margin). 


Description 


The SET MARGINS command affects only the display of source lines. It does not 
SL the^play of other debugger output, as from an EXAMINE command. 

The SET MARGINS command is useful for controlling the display of “ de 

ssassHS 

value of 255) to truncate lines and prevent them from wrapping. 

The SET MARGINS command is useful mostly in line (noscreen) mode. In line 

rip the SET MARGINS command affects the display of source lines resu g 

from J^^E E^IINE/SOURCE, SEARCH, or STEP command, or when a 

breakpoint, tracepoint, or watchpoint is triggered. 

rip +V 10 qvt MARGINS command has no effect on the display of 
In screen mode, the oh I ivu\i\u\li>io . i Thprefore it 

source lines in a source f tommand, since that 

does not affect the output of a TYP MARGINS command affects only 

« “b 

example after a STEP command has been executed). However, sue s ™ e 
display is normally suppressed tf ym. enable well as’ 

because that sequence issues the SE1 

SET MODE SCREEN to eliminate redundant source display. 
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SET MARGINS 


Examples 


thf^ an? 1 ™?' d T‘T \ S0UrCe tae Btartin S at character position 1 
The first eight character “T 

and cannot be manipulated by the SET MARGINS command "umber 

S £tX b s“'e“fief'— - “ “*» - * - the 

^mblZ^^e^eft^ftoe^olon Md* the^riglRmm^n 8 !^ 8 the*number 

margin to that numtar^toa^Zeright 8 ™5n“JZtagT' "* ^ 

- - - 

Related commands: 

SET STEP [NO]SOURCE 
SHOW MARGINS 


1. DBG> SHOW MARGINS 

left margin: 1 , right margin: 255 
DBG> TYPE 14 
module FORARRAY 

DBG> 4 ' DIMENSION IARRAY(4:5,5), VECTOR(IO), I3D(3,3,4) 

TTfis mmmple displays the default margin settings for a line of source code (1 

2. DBG> SET MARGINS 39 
DBG> SHOW MARGINS 

left margin: 1 , right margin: 39 
DBG> TYPE 14 
module FORARRAY 

DBG> 4- ’ DIM£ NSI0N IARRAY (4:5, 5), VECTOR 

™u S chare P 'theriZ h0W ““ di , S1>lay ° f1 ,ine of source changes when 
you cnange the right margin setting from 255 to 39. 

3. DBG> SET MARGINS 10:45 
DBG> SHOW MARGINS 

left margin: 10 , right margin: 45 
DBG> TYPE 14 
module FORARRAY 

DBG> 4: IMENSI0N IARRAY(4:5,5), VECTOR(10), 

ma^rfchtnZd* 116 diSP ' ay ° f '‘ he ““ ““ ° f s °"<* •"» both 
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SET MARGINS 


4 . DBG> SET MARGINS : 100 
DBG> SHOW MARGINS 

left margin: 10 , right margin: 100 
DBG> 

This example shows how to change the right margin setting while retaining 
the previous left margin setting. 

5 . DBG> SET MARGINS 5: 

DBG> SHOW MARGINS 

left margin: 5 , right margin: 100 

DBG> . . ,, 

This example shows how to change the left margin setting while retaming the 

previous right margin setting. 
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SET MODE 


Format 


Parameters 


Enables or disables a debugger mode. 


SET MODE mode[, ... ] 


mode 

8 debUg6er mode *° * or disabled. Valid keywords are as 

DYNAMIC (Default.) Enables dynamic mode. When dynamic 

mode is enabled, the debugger sets modules and 
images automatically during program execution so 

AT^ t TYr^Tn typiCa y do not have to enter the SET 
ODULE or SET IMAGE command. Specifically, 

w enever the debugger interrupts execution 
(wheneyer the debugger prompt is displayed) 
the debugger automatically sets the module and 
image that contain the routine in which execution 
is currently suspended. If the module or im age 
is already set, dynamic mode has no effect on 
that module or image. The debugger issues an 
informational message when it sets a module or 
image automatically. 

m ° de - BeCauSe Clonal memory 
is allocated when a module or image is set, you 

might want to disable dynamic mode if performance 
becomes a prob em (you can also free up memory by 

Mn™ 1 r 1 ? f L ni0duleS and ima & es with the CANCEL 7 
MODULE and CANCEL IMAGE commands). When 

ynamic mode is disabled, you must set modules and 

™ ag ®® expllcltly with the SET MODULE and SET 
IMAGE commands. 


NODYNAMIC 


G_FLOAT 


NOG.FLOAT 


Specifies that the debugger interpret double-precision 

FLOAT^T C T tants T tered in expressions as G_ 

,I T (does not affect the interpretation of variables 
declared in your program). 

(Default.) Specifies that the debugger interpret 
double-precision floating-point constants entered 
m expressions as D_FLOAT (does not affect the 
interpretation of variables declared in your program). 


CD-181 








SET MODE 


INTERRUPT 


NOINTERRUPT 


(Default. Applies to a naukiprocess debugng 
configuration—that is, when DBG$PROCESb has 
the value MULTIPROCESS.) Specifies that, when 
program execution is suspended in any process, the 
debugger interrupts execution in any ot er processe 
that were executing images and prompts for mpu . 

(Applies to a multiprocess debugging confipiration— 
that is, when DBG$PROCESS has the value 
MULTIPROCESS.) Specifies that, when program 
execution is suspended in any process, the debugger 
take the following action: 

• If execution was suspended because of an 
unhandled exception, the debugger interrupts 
execution in any other processes that were 
executing images and prompts for input. 

• If execution was suspended because of a 
breakpoint or watchpoint or the completion of 
a STEP command, the debugger lets execution 
proceed in any other processes that were 
executing images and does not display the prompt 
unless execution is eventually suspended in all 
these processes. As long as execution continues 
in any process, the debugger does not prompt for 
input. In such cases, use Ctrl/C to interrupt al 
Drocesses and display the prompt. 


KEYPAD 


_Note - 

This parameter is not 
available in the DECwindows 
Motif interface to the 
debugger. 


>fault.) Enables keypad mode. When keypad mo e 
enabled, you can use the keys on the numeric 
ypad to perform certain predefined functions, 
veral debugger commands, especially useful m 
-een mode, are bound to the keypad keys. (See 
e Keypad_Definitions_CI help topic; also, use the 
IOW KEY command to determine the current key 
hnitions.) You can also redefine the key functions 
ith the DEFINE/KEY command. 
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NOKEYPAD 


LINE 


NOLINE 


fOPERANDS[=&eyw;ord] 


tNOOPERANDS 


fVAX specific 


- Note _ 

This parameter is not 
available in the DEC windows 
Motif interface to the 
debugger. 


Disables keypad mode. When keypad mode is 
disabled, the keys on the numeric keypad do not 
have predefined functions, nor can you assign 
debugger functions to those keys with DEFINE/KEY 
commands. 

(Default.) Specifies that the debugger display 
program locations in terms of line numbers, if 
possible. 

Specifies that the debugger display program locations 
as routine-name + byte-offset rather than in terms of 
line numbers. 

Specifies that the EXAMINE command, when used 
to examine an instruction, display the address and 
contents of the instruction’s operands in addition 
to the instruction and its operands. The level of 
information displayed about any nonregister operands 
depends on whether you use the keyword BRIEF or 
FULL. The default is OPERANDS=BRIEF. 

(Default.) Specifies that the EXAMINE command, 
when used to examine an instruction, display only 
the instruction and its operands. 
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SCREEN 


_ Note - 

This parameter is not 
available in the DECwindows 
Motif interface to the 
debugger. 


Enables screen mode. When screen mode is enabled, 
you can divide the terminal screen into rectangular 
regions, so different data can be displayed in different 
regions. Screen mode enables you to view more 
information more conveniently than the default, line- 
oriented, noscreen mode. You can use the predefined 
displays, or you can define your own. 

NOSCREEN 


_ Note - 

This parameter is not 
available in the DECwindows 
Motif interface to the 
debugger. 


(Default.) Disables screen mode. 

SCROLL 


_ Note - 

This parameter is not 
available in the DECwindows 
Motif interface to the 
debugger. 


(Default.) Enables scroll mode. When scroll mode 
is enabled, a screen-mode output or DO display is 
updated by scrolling the output line by line, as it is 
generated. 
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NOSCROLL 


SEPARATE 


NOSEPARATE 


SYMBOLIC 


NOSYMBOLIC 


- Note _ 

This parameter is not 
available in the DECwindows 
Motif interface to the 
debugger. 


Disables scroll mode. When scroll mode is disabled, 
a screen-mode output or DO display is updated only 
once per command, instead of line by line as it is 
generated. Disabling scroll mode reduces the amount 
of screen updating that takes place and can be useful 
with slow terminals. 

(Applies only to workstations running VWS.) Specifies 
that a separate window be created for debugger input 
and output. This feature is useful when debugging 
screen-oriented programs, because it moves all 
debugger displays out of the window that contains the 
programs input and output. The separate window is 
created with a height of 24 lines and a width of 80 
columns, emulating a VT-series terminal screen. 

(Default. Applies only to workstations running VWS.) 
Specifies that no separate window be created for 
debugger input and output. 


(Default.) Enables symbolic mode. When symbolic 
mode is enabled, the debugger displays the locations 
denoted by address expressions symbolically 
(if possible) and displays instruction operands 
symbolically (if possible). EXAMINE/NOSYMBOLIC 
can be used to override SET MODE SYMBOLIC for 
the duration of an EXAMINE command. 

Disables symbolic mode. When symbolic mode is 
disabled, the debugger does not attempt to symbolize 
numeric addresses (it does not cause the debugger 
to convert numbers to names). This is useful if 
you are interested in identifying numeric addresses 
rather than their symbolic names (if symbolic names 
exist for those addresses). When symbolic mode 
is disabled, command processing might speed up 
somewhat, because the debugger does not need to 
convert numbers to names. EXAMINE/SYMBOLIC 
can be used to override SET MODE NOSYMBOLIC 
for the duration of an EXAMINE command. 
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Description 

For details about the SET MODE command, see the parameter descriptions. The 
default values of these modes are the same for all languages. 

Related commands: 

EVALUATE 

EXAMINE 

DEFINE/KEY 

DEPOSIT 

DISPLAY 

(SET,SHOW,CANCEL) IMAGE 
(SET,SHOW,CANCEL) MODULE 
SET PROMPT 

(SET,SHOW,CANCEL) RADIX 
(SET,SHOW) TYPE 
(SHOW,CANCEL) MODE 
SYMBOLIZE 

Example 

DBG> SET MODE SCREEN 

This command puts the debugger in screen mode. 
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SET MODULE 


Loads the symbol records of a module 
symbol table (RST) of that image. 


in the current image into the run-time 


-- Note__ 

T he current image is either the main image (by default) or the image 
established as the current image by a previous SET IMAGE command. 


Format 

SET MODULE [module-name[, ... ]] 

Parameters 

module-name 

fP eC ^ S ^ module of the current image whose symbol records are loaded into 
the RST. Do not use the asterisk (*) wildcard character. Instead, use the /ATI. 
qualifier. Do not specify a module name with /ALL or /CALLS. 

Qualifiers 

/ALL 

Specifies that the symbol records of all modules in the current image be loaded 


/CALLS 


Sets all the modules that currently have routines 
already set, /CALLS has no effect on that module. 


on the call stack. If a module is 


/RELATED (default) 

/NORELATED 

(Applies to Ada programs.) Controls whether the debugger loads into the RST 
the symbol records of a module that is related to a specified module through 
a with-clause or subunit relationship. Once loaded, you can reference names 
ec aredin related modules within debugger commands exactly as you reference 
them within the Ada source code. 


Description 


Symbol records must be present in the RST if the debugger is to recognize and 
properly interpret the symbols declared in your program. The process by which 

the symbol records of a module are loaded into the RST is called setting a 
module. 

At debugger startup, the debugger sets the module containing the transfer 

nwAmn ™ am ? r0gram) ' By default > dynamic mode is enabled (SET MODE 
DYNAMIC). Therefore, the debugger sets modules (and images) automatically 
as e program executes so that you can reference symbols as you need them. 

peci ca y, w enever execution is suspended, the debugger sets the module and 
image containing the routine in which execution is suspended. In the case of 
Ada programs as a module is set dynamically, its related modules are also set 
automatically, by default, to make the appropriate symbols accessible (visible). 
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Examples 


Dynamic mode makes accessible most of the symbols you might need to reference. 
If you need to reference a symbol in a module that is not already set, proceed as 

follows: 

• If the module is in the current image, use the SET MODULE command to set 
the module where the symbol is defined. 

• If the module is in another image, use the SET IMAGE command to make 
that image the current image, then use the SET MODULE command to set 
the module where the symbol is defined. 

If dynamic mode is disabled (SET MODE NODYNAMIC), only the module 
containing the transfer address is set automatically. You must set any other 
modules explicitly. 

If you use the SET IMAGE command to establish a new current image, all 
modules previously set remain set. However, only the symbols in the set modules 
of the current image are accessible. Symbols in the set modules of other images 
are temporarily inaccessible. 

When dynamic mode is enabled, memory is allocated automatically to 
accommodate the increasing size of the RST. If dynamic mode is disabled, the 
debugger automatically allocates more memory as needed when you set a module 
or an image. Whether dynamic mode is enabled °r disabled, if performance 
becomes a problem as more modules are set, use the CANCEL MODULE 
command to reduce the number of set modules. 

If a parameter in a SET SCOPE command designates a program location in a 
module that is not already set, the SET SCOPE command sets that module. 

For information specific to Ada programs, see the Language ADA help topic. 


Related commands: 

(SET,SHOW,CANCEL) IMAGE 
SET MODE [N01DYNAMIC 
(SHOW,CANCEL) MODULE 


1. DBG> SET MODULE SUB1 

This command sets module SUB1 (loads the symbol records of module SUB1 
into the RST). 

2 . DBG> SET IMAGE SHARE3 
DBG> SET MODULE MATH 
DBG> SET BREAK %LINE 31 

In this example, the SET IMAGE command makes shareable image SHARE3 
the current image. The SET MODULE command sets module MATH in 
image SHARE3. The SET BREAK command sets a breakpoint on hne 31 01 

module MATH. 


CD-188 




SET MODULE 


symbols 

language 

size 

yes 

MACRO 

432 

no 

FORTRAN 

280 

no 

Image 

0 

no 

Image 

0 

no 

Image 

0 

no 

Image 

0 

no 

Image 

0 


DBG> SHOW MODULE/SHARE 
module name 

F00 
MAIN 

SHARE$DEBUG 
SHARE$LIBRTL 
SHARE$MTHRTL 
SHARE$SHARE1 
SHARESSHARE2 

total modules: 17. 

DBG> SET MODULE SHARE$SHARE2 
DBG> SHOW SYMBOL * IN SHARE$SHARE2 

In this example, the SHOW MODULE/SHARE command identifies 
all modules in the current image and all shareable images (the 
names of the shareable images are prefixed with SHARE$). The SET 
SHARE$SHARE2 command sets the shareable image module 
SHARE$SHARE2. The SHOW SYMBOL command identifies any universal 

!f n o?!l defined m the shareable ima ge SHARE2. For more information, see 
the SHOW MODULE/SHARE command. 


bytes allocated: 162280. 
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SET OUTPUT 

Enables or disables a debugger output option. 

Format 

SET OUTPUT output-option[, . . . ] 

Parameters 

option to be enabled or disabled. Valid keywords are as 

Specifies that debugger input and output be recorded 
in a log file. If you specify the log file by the SET LOG 
command, the debugger writes to that file; otherwise, by 
default the debugger writes to SYS$DISK[]:DEBUG.LOG. 
(Default.) Specifies that debugger input and output not be 
recorded in a log file. 

Specifies that, while in screen mode, the screen contents be 
recorded in a log file as the screen is updated. To log the 
screen contents you must also specify SET OUTPUT LOG. 
See the description of the LOG option regarding specifying 
the log file. 

(Default.) Specifies that the screen contents, while in 
screen mode, not be recorded in a log file. 

TERMINAL 

_ Note - 

This parameter is not available in 
the DECwindows Motif interface to 
the debugger. 


output-option 

Specifies an output 
follows: 

LOG 

NOLOG 

SCREEN.LOG 

NOSCREENLOG 


(Default.) Specifies that debugger output be displayed at 
the terminal. 
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NOTERMINAL 


-Note_ 

This parameter is not available in 
the DECwindows Motif interface to 
the debugger. 


VERIFY 


NOVERIFY 


Specifies that debugger output, except diagnostic messages, 
not be displayed at the terminal. 

Specifies that the debugger echo, on the current output 
device, each input command string that it is executing from 
a command procedure or DO clause. The current output 
device is by default SYS$OUTPUT (your terminal) but can 
be redefined with the logical name DBG$OUTPUT. 

(Default.) Specifies that the debugger not display each 
input command string that it is executing from a command 
procedure or DO clause. 


Description 

Debugger output options control the way in which debugger responses to 
commands are displayed and recorded. For details about the SET OUTPUT 
command, see the parameter descriptions. 

Related commands: 


@ (Execute Procedure) 
(SET,SHOW) ATSIGN 
(SET,SHOW) LOG 
SET MODE SCREEN 
SHOW OUTPUT 


Example 


DBG> SET OUTPUT VERIFY,LOG,NOTERMINAL 

This command specifies that the debugger take the following actions: 

■ that “ is executin6 a1 1—*» 
Record debugger output and user input in a log file (LOG) 
(NOTERMINAL) Ut * ^ termina1 ’ exce P t diagnostic messages 
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SET PROCESS 

Establishes the visible process, changes characteristics of one or more processes, 
or enables/disables dynamic process setting. 

Applies to a multiprocess debugging configuration (when DBG$PROCESS has the 
value MULTIPROCESS). 


Format 

SET PROCESS [process-spec[, ... ]] 


Parameters 


currently under debugger control. Use any of the following 


process-spec 

Specifies a process 
forms: 

[%PROCESS_NAME] proc-name 

[%PROCESS_NAME] "proc-name" 

%PROCESS_PID proc-id 

%PROCESS_NUMBER proc-number 
(or %PROC proc-number) 

proc-group-name 

%NEXT_PROCESS 

%PREVIOUS_PROCESS 

%VISIBLE_PROCESS 


The process name, if that name 
contains no space or lowercase 
characters. The process name can 
include the asterisk (*) wildcard 
character. 

The process name, if that name 
contains space or lowercase 
characters. You can also use 
apostrophes (') instead of quotation 
marks ("). 

The process identification number 
(PID, a hexadecimal number). 

The number assigned to a process 
when it comes under debugger 
control. Process numbers appear 
in a SHOW PROCESS display. 

A symbol defined with the DEFINE 
/PROCESS_GROUP command to 
represent a group of processes. 

Do not specify a recursive symbol 
definition. 

The process after the visible process 
in the debugger’s circular process 
list. 

The process previous to the visible 
process in the debugger’s circular 
process list. 

The process whose call stack, register 
set, and images are the current 
context for looking up symbols, 
register values, routine calls, 
breakpoints, and so on. 
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Qualifiers 


Description 


Yoii can also use the asterisk (*) wildcard character or the / ATI, qualifier to 
specify all processes. Do not specify a process with /ALL or /[NONDYNAMIC 

selected ^ * Pr0C6SS ^ /ALL ^ /[N0]H0LD > the visible process is 


/ALL 

Applies the SET PROCESS command to all processes. 

/DYNAMIC (default) 

/NODYNAMIC 

Controls whether dynamic process setting is enabled or disabled. When dynamic 
process setting is enabled (/DYNAMIC), whenever the debugger suspends 
execution and displays its prompt, the process in which execution is suspended 
becomes the visible process automatically. When dynamic process setting is 
disabled (/NODYNAMIC), the visible process remains unchanged until you 
specify another process with the SET PROCESS/VISIBLE command. 

/HOLD 

/NOHOLD (default) 

/HOLD puts a specified process on hold. This prevents images in that process 
from executing when you enter a GO, STEP, or CALL command, unless the 
process is the visible process. A hold condition in the visible process is ignored. 

The /NOHOLD qualifier releases a specified process from a hold condition. This 
permits images in that process to execute when you enter a GO, STEP or CALL 
command, regardless of which process is the visible process. 

J bebe J a ™ r de p A n T b T ed also applies when y° u use DO command to broadcast 
a uu, olLL, or CALL command to specific processes. 

For information on the effects of these commands on processes that have or have 
not been put on hold, see the GO, STEP, CALL, EXIT, and QUIT commands. 

/VISIBLE 

Makes the specified process the visible process. This switches your debugging 
context to the specified process, so that symbol lookups and the setting of 

A 7 TQmr 01 ^ tS ’ and S ° ° n ’ are d ° ne in the context of that process. When using 
/VlolLLL, you must specify one process. 


The SET PROCESS command establishes the visible process or changes 
characteristics of one or more processes. 

By default, commands are executed in the context of the visible process. The 
visible Process is the process that is your current debugging context. Symbol 

lookups and the setting of breakpoints, and so on, are done in the context of the 
visible process. 

The DO command enables you to execute commands in the context of specific 

PROCF^/vt^trt processes - , Tbe D0 command is equivalent to entering a SET 
PKOCESS/VISIBLE command for each process specified (or for all processes if 
no process is specified with the DO command) and then entering the specified 
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Examples 


Dynamic process setting is enabled by default and is controlled with 
/[NO]DYNAMIC. When dynamic process setting is enabled, whenever the 
debugger suspends program execution and displays its prompt, the process in 
which execution is suspended becomes the visible process automatically. 

Related commands: 


CALL 

DO 

EXIT 

GO 

QUIT 

SHOW PROCESS 
STEP 


1. DBG_1> SET PROCESS/HOLD/ALL 
DBG_1> SHOW PROCESS/ALL 
Number Name Hold State 

* 1 TEST_X YES step 

2 TEST_Y YES break 

DBG 1> 


Current PC 
PROG\%LINE 50 
PROG\%LINE 71 


The SET PROCESS/HOLD/ALL command puts all processes on hold. This is 
confirmed in the SHOW PROCESS/ALL display. 


2 . 


)BG 1> SET PROCESS/NOHOLD %VISIBLE_PROCESS 
)BG“1> SHOW PROCESS/ALL 

Number Name Hold State Current PC 

: ]_ TEST X step PROG\%LINE 50 

2 TEST _ Y YES break PROG\%LINE 71 

w; 1> 


The SET PROCESS/NOHOLD %VISIBLE_PROCESS command releases 
the visible process from the hold condition. This is confirmed in the SHOW 
PROCESS/ALL display. 


3 DBG_1> SET PROCESS TEST_Y 
DBG 2> SHOW PROCESS 

Number Name Hold State Current PC 

* 2 TEST Y YES break PROG\ILINE 71 

DBG_2> 

The SET PROCESS TEST_Y command makes process TEST.Y the visible 
process. The SHOW PROCESS command displays information about the 
visible process by default. 


4. 


DBG 1> SET PROCESS/HOLD/ALL 
DBG_1> DO (EXAMINE X; STEP) 

For %PROCESS_NUMBER 1 
MAIN_PROG\X: 78 

For %PROCESS_NUMBER 2 
TEST\X* 29 

stepped to MAIN_PROG\%LINE 26 in %PROCESS_NUMBER 1 
26: K = K + 1 

DBG 1> 


1 this example, the SET PROCESS/HOLD/ALL command puts all processes 
n hold. The DO command broadcasts the EXAMINE X and STEP commands 
i all processes (processes 1 and 2, in this example). The STEP command is 
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executed in the context of process 1, because a hold condition in the visible 
process is ignored. Because process 2 is on hold, execution is inhibited in that 
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SET PROMPT 

Changes the debugger prompt string to your personal preference. 

Format 

SET PROMPT [prompt-parameter] 


Parameters 


Qualifiers 


Specifies the new prompt string. If the string contains spaces, semicolons (,), or 
lowercase characters, you must enclose it in quotation marks (") or apostrophes 
('). If you do not specify a string, the current prompt string remains unchanged. 

By default, the prompt string is DBG> for a nonmultiprocess debugging 
configuration (when the logical name DBG$PROCESS is undefined or as 
the value DEFAULT). 

Bv default, for a multiprocess debugging configuration (when DBG$PROCESS has 
the value MULTIPROCESS), the prompt string consists of a process-independent 
prefix (specified by prompt-parameter) and a process-specific suffix (specified by 
/[NO]SUFFIX). The suffix changes automatically as the visible process changes. 


/SUFFIX[=process-identifier-type] (default) 

Apphes F to X a multiprocess debugging configuration (when DBG$PROCESS has the 
value MULTIPROCESS). 

The /SUFFIX qualifier enables "dynamic prompt setting". As a result, the 
prompt string includes a process-specific suffix that automatically identifies the 
visible process. This is the default. 

The /NOSUFFIX qualifier disables dynamic prompt setting. As a result, the 
prompt string does not include a process-specific suffix and does not change when 
another process becomes the visible process. 

By default, when you start the debugger to debug a multiprocess program, the 
prompt string is DBG_1>. This indicates that dynamic prompt setting is enabled 
and that the visible process is process 1 (the first process connected to t e 
debugger). You can control the process-specific prompt-stnngsuffixby speafrg 
one of the following process-identifier-type keywords with the /SUFFIX qualifier. 


PROCESS_NAME 

PROCESSJNTUMBER 

PROCESS_PID 


The display-name suffix is the process name. 

The display-name suffix is the process number (as shown 
in a SHOW PROCESS display). 

The display-name suffix is the process identification 
number (PID). 


The following table illustrates the possible kinds of prompt strings for a 
multiprocess debugging configuration. The entire prompt string depends on the 
prompt-parameter command parameter (which controls the process-mdependent 
prefix), and on the values of/[NO]SUFFIX and the process-identifier-type keyword 
(which control the process-specific suffix). 
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Description 


Examples 


Prompt Parameter 
(prefix) 

Qualifier and Keyword (suffix) 

Resulting Prompt String 

none 

none 

unchanged 

none 

/NOSUFFIX 

DBG> 

none 

/SUFFIX 

T>BG_j>roc-number> 1 

none 

/SUFFIX=PROCESS_NAME 

proc-name> 

none 

/SUFFIX=PROCESS_NUMBER 

proc-number> 

none 

/SUFFIX=PROCESS_PID 

pid> 

XYZ_ 

/NOSUFFIX 

XYZ_> 

XYZ_ 

/SUFFIX 

XY Z_proc-number> 

XYZ_ 

/SUFFIX=PROCESS_NAME 

XYZ_j)roc-name> 

XYZ_ 

/SUFFIX=PROCESS_NUMBER 

XYZ_j)roc-number> 

XYZ_ 

i n 

/SUFFIX=PROCESS_PID 

XYZ pid> 


equivalent to entermg°the foilowmg^commanff 1 " 8 configuratlon ls DBG process-number>, which ii 


DBG> SET PROMPT/SUFFIX=PROCESS NUMBER "DBG 


/POP 

/NOPOP (default) 

(Applies only to workstations running VWS.) The /POP qualifier causes the 
debugger window to pop over other windows and become attached to the 
keyboard when the debugger prompts for input. The /NOPOP qualifier disables 

attached^Th * d , ebugger Wmdow is not P°PP ed over other windows and is not 
attached to the keyboard automatically when the debugger prompts for input) 


^SSSr 1 enabIes you to tailor the debugger promi>t string 40 

nRr'JPROP^I t m ^ tipr0( ; eSS debuggin ^ configuration (when the logical name 
DBG$ p R° CESS has the value MULTIPROCESS), /[NOJSUFFIX enables you to 
specify a process-specific prompt-string suffix. y 

tf you are using the debugger at a workstation, /[NOJPOP enables you to control 

whether the debugger window is popped over other windows whenever the 
debugger prompts for input. wnenever me 

Related commands: (SET,SHOW) PROCESS. 


1. DBG> SET PROMPT "$ » 

$ SET PROMPT "dbg: " 
dbg: SET PROMPT "DBG> " 
DBG> 


In this example, the successive SET PROMPT commands change the 
debugger prompt from “DBG>” to to “d b g then back to “DBG>”. 
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2. DBG_1> SET PROMPT/NOSUFFIX "dbg> " 
dbg> SET PROMPT/SiUFFIX 

DBG 1> SET PROMPT/SUFFIX=PROCESS_NUMBER "xyz_ 
xyz 1> SET PROMPT/SUFFIX=PROCESS_NAME 
SMITH> SET PROMPT/SUFFIX=PROCESS_NAME "John 
John SMITH> SET PROMPT/SUFFIX=PROCESS_PID 
20800E4D> 

In this example, the successive SET PROMPT commands show the effects of 
/[NO]SUFFIX and the prompt-parameter for multiprocess programs. 
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SET RADIX 


Format 


Parameters 


/OWRRrnVt ” diX for „ tl ;« ! and display of integer data. When used with 
radix ’ causes a11 data to be displayed as integer data of the specified 


SET RADIX radix 


Qualifiers 


radix 

Specifies the radix to be established. Valid keywords are as follows: 


BINARY 
DECIMAL 

DEFAULT 

OCTAL 

HEXADECIMAL 

fAlpha specific 


Sets the radix to binary. 

Sets the radix to decimal. This is the default for all 
anguages except BLISS, MACRO—32, and fMACRO—64. 

Sets the radix to the language default. 

Sets the radix to octal. 

So? 6 ,™ r o adiX t0 hexadecimal - This is the default for 
BLISS, MACRO-32, and tMACRO-64. 


Description 


/INPUT 

Setsonly the input radix (the radix for entering integer data) to the specified 

/OUTPUT 

Setsonly the output radix (the radix for displaying integer data) to the specified 

/OVERRIDE 

Causes all data to be displayed as integer data of the specified radix. 


££££ StefotSnfS h ° W ‘ h6 “* **>■ 

• Integer data that you specify in address expressions or language expressions. 

Integer data that is displayed by the EXAMINE and EVALUATE commands. 
The default radix for both data entry and display is decimal for most languages. 

defeTrZThexa^ilTi 0 " 5 ”* ^ ““ MACR0 ~^ *»ich have a 
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SET RADIX 


Alpha 


Examples 


On Alpha processors, the exceptions are BLISS, MACRO 32, and MACRO 64, 
which have a default radix of hexadecimal. ♦ 

The SET RADIX command enables you to specify a new radix for data entry or 
display (the input radix and output radix, respectively). 

If you do not specify a qualifier, the SET RADIX command changes both the input 
and output rate. If you specify /INPUT or /OUTPUT, the command changes the 
input or output radix, respectively. 

Using SET RADIX/OVERRIDE changes only the output radix but causes all data 
(not just data that has an integer type) to be displayed as integer data of the 
specified radix. 

Except when used with /OVERRIDE, the SET RADIX command does not affect 
the interpretation or display of noninteger values (such as real or enumeration 

type values). 

The EVALUATE, EXAMINE, and DEPOSIT commands have radix qualifiers 
(/BINARY, /HEXADECIMAL, and so on) which enable you to ovemde.forthe 
duration of that command, any radix previously established with SET RADIX 
SET RADIX/OVERRIDE. 

You can also use the built-in symbols %BIN, %DEC, %HEX and %OCT in 
address expressions and language expressions to specify that an integerAltera 
should be interpreted in binary, decimal, hexadecimal, or octal radix. See the 
Built_in_Symbols help topic. 

Related commands: 

DEPOSIT 

EVALUATE 

EXAMINE 

(SET,SHOW,CANCEL) MODE 
(SHOW,CANCEL) RADIX 


1. DBG> SET RADIX HEX 

This command sets the radix to hexadecimal. This means that, by default, 
integer data is interpreted and displayed in hexadecimal radix. 


2 . DBG> SET RADIX/INPUT OCT 

This command sets the radix for input to octal. This means that, by default, 
integer data that is entered is interpreted in octal radix. 

3 . DBG> SET RADIX/OUTPUT BIN 

This command sets the radix for output to binary. This means that, by 
default, integer data is displayed in binary radix. 


4 . 


DBG> set radix/override decimal 


This command sets the override radix to decimal, 
default, all data (not just data that has an integer 
decimal integer data. 


This means that, by 
type) is displayed as 
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SET SCOPE 


Format 


Parameters 


Establishes how the debugger looks up symbols (variable names, routine names 
me numbers, and so on) when a path-name prefix is not specified. 


SET SCOPE location^ .. . ] 


Qualifiers 


path-name prefix 


location 

Denotes a program region (scope) to be used for the interpretation of symbols that 
you specify without a path-name prefix. A location can be any of the following 
unless you specify /CURRENT or /MODULE. s ’ 

Specifies the scope denoted by the path-name prefix. 

A path name prefix consists of the names of one or 
more nesting program elements (module, routine, block, 
and so on), with each name separated by a backslash 
character (\ ). When a path-name prefix consists of 
more than one name, list a nesting element to the left 
of the backslash and a nested element to the right of 
the backslash. A common path name prefix format is 
module \ routine \ block \. 

If you specify only a module name and that name is 
the same as the name of a routine, use /MODULE; 
otherwise, the debugger assumes that you are specifying 
the routine. 

Specifies the scope denoted by the routine which is n 
levels down the call stack (n is a decimal integer). A 
scope specified by an integer changes dynamically as the 
program executes. The value 0 denotes the routine that 
is currently executing, the value 1 denotes the caller of 
that routine, and so on down the call stack. The default 
scope search list is 0,1,2, ... ,n, where n is the number 
of calls in the call stack. 

Specifies the global scope—that is, the set of all program 
locations in which a global symbol is known. The 
definition of a global symbol and the way it is declared 
depends on the language. 

When you specify more than one location parameter, you establish a scope search 
ist. If the debugger cannot interpret the symbol using the first parameter, it uses 
the next parameter, and continues using parameters in order of their specification 
until it successfuHy interprets the symbol or until it exhausts the parameters 


/CURRENT 

Establishes a scope search list that is like the default search list ( 0,1,2 n) 
but starts at the numeric scope specified as the command parameter. Scope 0 is 
the PC scope, and n is the number of calls in the call stack. 


\ (backslash) 
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SET SCOPE 


When using SET SCOPE/CURRENT, note the following conventions and behavior: 

• The default scope search list must be in effect when the command is entered. 
To restore the default scope search list, enter the CANCEL SCOPE command. 

• The command parameter specified must be one (and only one) decimal integer 
from 0 to n. 

• In screen mode, the command updates the predefined source, instruction, and 
register displays SRC, INST, and REG, respectively, to show the routine on 
the call stack in which symbol searches are to start. 

• The default scope search list is restored when program execution is resumed. 

Indicates that the name specified as the command parameter is a module name 

and not a routine name. You need to use /MODULE only if you specify a modu e 

name as the command parameter and that module name is the same as the name 

of a routine. 


Description 


By default, the debugger looks up a symbol specified without a path name prefix 
according to the scope search list 0,1,2, where n is the number of calls 

in the call stack. This scope search list is based on the current PC value and 
changes dynamically as the program executes. The default scope search lis 
specifies that a symbol lookup such as EXAMINE X first looks for X in t e 
routine that is currently executing (scope 0, also known as the PC scope); i no 
X is visible there, the debugger looks in the caller of that routine (scope 1), and 
so on down the call stack; if X is not found in scope n, the debugger searches the 
rest of the run-time symbol table (RST)-that is, all set modules and the global 
symbol table (GST), if necessary. 

In most cases, this default scope search list enables you to resolve ambiguities 
in a predictable, natural way that is consistent with language rules But if you 
cannot access a symbol that is defined multiple times, use either of the following 

techniques: 

• Specify the symbol with a path-name prefix. The path-name prefix consists 
of any nesting program units (for example, module\routine\block) that are 
necessary to specify the symbol uniquely. For example. 

DBG> EXAMINE MOD4\ROUT3\X 
DBG> TYPE MOD4\27 

. Establish a new default scope (or a scope search list) for symbol lookup by 
using the SET SCOPE command. You can then specify the symbol without 
using a path-name prefix. For example: 

DBG> SET SCOPE MOD4,\ROUT3 
DBG> EXAMINE X 
DBG> TYPE 27 

The SET SCOPE command is useful in those cases where otherwise you would 
need to use a path name repeatedly to specify symbols. 

To restore the default scope search list, use the CANCEL SCOPE command. 

When the default scope search list is in effect, you can use the SET SCOPE 
/CURRENT command to specify that symbol searches start at a numeric scope 
other than scope 0, relative to the call stack (for example, scope 2). 
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SET SCOPE 


Examples 


When you use the SET SCOPE command, the debugger searches only the 
program locations you specify explicitly, unless you specify /CURRENT Also the 
scope or scope search list established with a SET SCOPE command remains in 
e ect until you restore the default scope search list or enter another SET SCOPE 
command However, if you specify /CURRENT, the default scope search list is 
restored whenever program execution is resumed. 


The SET SCOPE command updates 
only if you specify /CURRENT. 


a screen-mode source or instruction display 


If a name you specify in a SET SCOPE command is the name of both a module 

SET a qmp™Snm'S‘ 6Ser SetS /!? *° * he In cases, use the 

SET SCOPE/MODULE command if you want to set the scope to the module. 

If you specify a module name in a SET SCOPE command, the debugger "sets" 
that module if it is not already set. However, if you want only to set a module 
use the SET MODULE command rather than the SET SCOPE command, to avoid 
the possibility of disturbing the current scope search list. 


For information specific to Ada programs, see the Language ADA help topic. 
Related commands: 


CANCEL ALL 

SEARCH 

SET MODULE 

(SHOW,CANCEL) SCOPE 

SHOW SYMBOL 

SYMBOLIZE 

TYPE 


1. DBG> EXAMINE Y 

%DEBUG-W-NOONIQUE, symbol 'V is not unique 
DBG> SHOW SYMBOL Y 
data CHECK_IN\Y 
data INVENTORY\COUNT\Y 
DBG> SET SCOPE INVENTORY\COUNT 
DBG> EXAMINE Y 
INVENTORY\COUNT\Y: 347.15 
DBG> 


In tins example, the first EXAMINE Y command indicates that symbol Y is 

itf "tLTSw Cann0t be reS ° lved fr0m the current sc °P e search 

list The SHOW SYMBOL command displays the different declarations of 

symbol Y. The SET SCOPE command directs the debugger to look for symbols 

without path-name prefixes in routine COUNT of module INVENTORY. The 

subsequent EXAMINE command can now interpret Y unambiguously. 


2. DBG> CANCEL SCOPE 

DBG> SET SCOPE/CURRENT 1 

In th jf , eX f“ P ! e ’ the CANCEL SC0PE command restores the default scope 
search list (0,1,2, . . . ,n). The SET SCOPE/CURRENT command then 

JnnTr S ^ t !; e i SC0Pe !w r u h U n t0 1>2> • '• 80 that s 3 ™bol searches start with 

scope i (that is, with the caller of the routine in which execution is currently 

suspended). The predefined source and instruction displays SRC and INST 
respectively, are updated and now show the source and instructions for the’ 
caller of the routine in which execution is suspended. 
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SET SCOPE 


3. DBG> SET SCOPE 1 
DBG> EXAMINE %R5 

In this example, the SET SCOPE command directs the debugger to look for 
symbols without path-name prefixes in scope 1 (that is, in the caller of the 
routine in which execution is suspended). The EXAMINE command then 
displays the value of register R5 in the caller routine. The SET oCUP 
command without /CURRENT does not update any source or instruction 

display. 

4 . DBG> SET SCOPE 0, STACKS\R2, SCREEN 

This command directs the debugger to look for symbols without path name 
prefixes according to the following scope search list. First the debugger looks 
in the PC scope (denoted by 0). If the debugger cannot find a specified symbol 
in the PC scope, it then looks in routine R2 of module STACKS. If necessary, 
it then looks in module SCREEN. If the debugger still cannot find a specified 
symbol, it looks no further. 


global X 
local X 

same as ALPHA\X 


5 . DBG> SHOW SYMBOL X 
data ALPHA\X 
data ALPHA\BETA\X 
data X (global) 

DBG> SHOW SCOPE 

scope: 0 [ = ALPHA\BETA ] 

DBG> SYMBOLIZE X 
address ALPHA\BETA\%RO: 

ALPHA\BETA\X 
DBG> SET SCOPE \ 

DBG> SYMBOLIZE X 
address 00000200: 

ALPHA\X 

address 00000200: (global) 

X 

DBG> 

In this example, the SHOW SYMBOL command indicates that there are 
two declarations of the symbol X-a global ALPHA\X (shown twice) and a 
local ALPHA\ BETA\ X. Within the current scope, the local declaration otx 
(ALPHAX BETA\ X) is visible. After the scope is set to the global scope (&E1 
SCOPE \), the global declaration of X is made visible. 
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SET SEARCH 


SETSEARCH 


Format 


Parameters 


Description 


Establishes default qualifiers (/ALL or /NEXT, /IDENTIFIER or /STRING) for the 
SEARCH command. 


SET SEARCH search-default[, ... ] 


search-default 

Specifies a default to be established for the SEARCH command. Valid keywords 
(which correspond to SEARCH command qualifiers) are as follows: 

Subsequent SEARCH commands are treated as SEARCH/ALL 
rather than SEARCH/NEXT. 

Subsequent SEARCH commands are treated as SEARCH 
/IDENTIFIER, rather than SEARCH/STRING. 

(Default.) Subsequent SEARCH commands are treated as 
SEARCH/NEXT, rather than SEARCH/ALL. 

(Default.) Subsequent SEARCH commands are treated as 
SEARCH/STRING, rather than SEARCH/IDENTIFIER. 


ALL 


IDENTIFIER 


NEXT 


STRING 


| ET SEARCH command establishes default qualifiers for subsequent 
SEARCH commands. The parameters that you specify with SET SEARCH have 
the same names as the qualifiers for the SEARCH command. The qualifiers 
determine whether the SEARCH command: (1) searches for all occurrences of a 
S tnng (ALL) or only the next occurrence (NEXT); and (2) displays any occurrence 
of the stnng (STRING) or only those occurrences in which the string is not 
bounded on either side by a character that can be part of an identifier in the 
current language (IDENTIFIER). 

Ip U A^U 0Verride the current SEARCH default for the duration of a single 
SEARCH command by specifying other qualifiers. Use the SHOW SEARCH 
command to identify the current SEARCH defaults. 

Related commands: 

SEARCH 

(SET,SHOW) LANGUAGE 
SHOW SEARCH 
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SET SEARCH 


Example 

DBG> SHOW SEARCH 

search settings: search for next occurrence, as a string 

DBG> SET SEARCH IDENTIFIER 
DBG> SHOW SEARCH 

search settings: search for next occurrence, as an identifier 

DBG> SET SEARCH ALL 
DBG> SHOW SEARCH 

search settings: search for all occurrences, as an identifier 
DBG> 

In this example, the SET SEARCH IDENTIFIER command directs the debugger 
to search for an occurrence of the string in the specified range but display the 
string only if it is not bounded on either side by a character that can be part of 
an identifier in the current language. 

The SET SEARCH ALL command directs the debugger to search for (and display) 
all occurrences of the string in the specified range. 
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SETSOURCE 


Format 


Parameters 


Specifies a directory search list, a directory search method, or both a list and a 
method for source files. 


SET SOURCE directory-spec[, . . . ] 


Qualifiers 


directory-spec 

Specifies any part of an OpenVMS file specification (typically a device/directory) 
that the debugger is to use by default when searching for a source file. For any 
part of a full file specification that you do not supply, the debugger uses the file 
specification stored in the module’s symbol record (that is, the file specification 
that the source file had at compile time). 

If you specify more than one directory in a single SET SOURCE command you 
create a source directory search list (you can also specify a search list logical 
name that is defined at your process level). In this case, the debugger locates the 
source file by searching the first directory specified, then the second, and so on 
until it either locates the source file or exhausts the list of directories. 


/EDIT 

(Applies mainly to Ada programs.) Specifies the directory search list used during 
execution of the debugger’s EDIT command. 

/EXACT (default) 

Specifies the directory search method used. In this case, the debugger searches 
or the exact version of the source file, as indicated in the debugger symbol table. 

/LATEST 

Specifies the directory search method used. In this case, the debugger searches 

for the latest version of the source file, that is, the highest-numbered version in 
your directory. 

/MODULE=module-name 

Specifies the directory search list used only for the designated module. You can 

append one or more of the qualifiers listed above to the SET SOURCE/MODULE 
command. 

/ORIGINAL 

(Applies to STDL programs only. Requires installation of the Correlation Facility 
(a separate layered product) and invocation of the Kept Debugger.) Specifies that 
the debugger display the original STDL source file, rather than the intermediate 
files produced during STDL compilation. 


Description 


By default the debugger expects a source file to be in the same director it was 
m at compile time. If a source file has been moved to a different directory since 
compile time, use the SET SOURCE command to specify a directory search list 
and search method to locate the file. 
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SET SOURCE 


Specifying the Directory Search List 

On OpenVMS systems Version 6.1, a complete OpenVMS file specification has the 
following format: 

node::device:[directory]file-name.file-type;version-number 

This format reflects the DECnet node name functionality used in the default 
version of DECnet shipped with the OpenVMS operating system. For more 
information, see the DECnet for OpenVMS Networking Manual. 

On OpenVMS systems running Version 6.1 or later and DECnet/OSI, a complete 
file specification can include expanded node designations, called full names, u 
names are hierarchically structured DECnet node names that can be stored in a 
DECdns naming service. Full names can be a maximum of 255 bytes long, in the 
following format: 

namespace:.directory .... directory.node-name 

In this syntax statement, namespace identifies the global naming service, 
directory ... .directory defines the hierarchical directory path within the naming 
service, and node-name is the specific object defining the DECnet node. 

For information on full names and suggestions for setting up a system of names, 
see the OpenVMS System Manager’s Manual: Tuning, Monitoring and, Complex 
Systems. For information on DECnet/OSI, see the DECnet/OSI for OpenVMS 
Introduction, Planning, and Glossary manual. 

If the full file specification of a source file exceeds 255 characters, the debugger 
cannot locate the file. You can work around this problem by first defining a logical 
name "X" (at DCL level) to expand to your long file specification, and then using 
the SET SOURCE X command. 

When compiling a program with the /DEBUG qualifier, if you use a rooted- 
directory logical name to specify the location of the source file make sure that it 
is a concealed rooted-directory logical name. If it is not concealed and you move 
the source file to another directory after compilation, you cannot then use the 
debugger SET SOURCE command to specify the new location of the source hie. 

To create a concealed rooted-directory logical name, append the /TRANSLATION. 
ATTR=CONCEALED qualifier to your DCL DEFINE command. 

Specifying the Directory Search Method 

When you issue a SET SOURCE command, be aware that one of the two 
Qualifiers —/LATEST or /EXACT—will always be active. These qualifiers affect 
the debugger search method. The /LATEST qualifier directs the debugger 
to search for the version last created (the highest-numbered version m your 
directory). The /EXACT qualifier directs the debugger to search for the version 
last compiled (the version recorded in the debugger symbol table created at 
compile time). For example, a SET SOURCE/LATEST command might search 
for SORT.FOR;3 while a SET SOURCE/EXACT command might search for 

SORT.FOR;l. 

If the debugger locates this version using the directory search list, it checks 
that the creation or revision date and time, file size, record format, an e 
organization are the same as the original compile-time source file. If these 
characteristics match, the debugger concludes that the original source file has 
been located in its new directory. 
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SET SOURCE 


Examples 


If ' the debugger cannot locate this version using the directory search list it 

**.*- ‘he closest revision date and timeTif s"; exists 

Me no S 7 ’,™ 1 ,™ > NOTORIGSRC message (-original version of source 
me not found ) when first displaying the source code. 

Specifying the /EDIT Qualifier 

The /ED IT qualifier is needed when the files used for the display of source code 
are different from the files to be edited by using the EDIT command. This 

qOTTRruT Wlth A ? P L 0gra ? S ' For Ada P^grams, the (SET, SHOW, CANCEL) 
SOURCE commands affect the search of files used for source display (the -copied" 

command i libraries); the (SET,SHOW,CANCEL) SOURCE/EDIT 

commands affect the search of the source files you edit when using the EDIT 

™V«Od“ DULE With /EDIT - 1,16 <• «her 

For information specific to Ada programs, type HELP Language ADA. 

Specifying the /ORIGINAL Qualifier 

Before you can use the /ORIGINAL qualifier in a SET SOURCE command, 

svstem^Rpf 101 I ? Separate la y ered Product) must be installed on your 

system Refer to Correlation Facility documentation for information on creatine a 
correlation library before debugging. creating a 

Then, invoke the Kept Debugger and issue the SET SOURCE/ORIGINAT 
command as follows: 

$ DEBUG/KEEP 

DBG> SET SOURCE/ORIGINAL 

DBG> RUN filename.EXE 

After issuing these commands, you can debug STDL source code in the same wav 
you debug any other supported language program. y 

Related commands: 

(SHOW,CANCEL) SOURCE 


1. DBG> SHOW SOURCE 

no directory search list in effect 
DBG> SET SOURCE [PROJA],[PROJB],[PETER.PR0JC1 
DBG> SHOW SOURCE 

source directory list for all modules, 
match the latest source file version* 
[PROJA] 

[PROJB] 

[PETER.PROJC] 


In this example, the SET SOURCE command specifies that the debugger 
should search directones (PROJA), [PROJB], and [PETER.PROJC], in that 
order, for the latest version of source files. 
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SET SOURCE 


2 . 


DBG> SET SOURCE/MODULE=CTEST/EXACT [],SYSTEM::DEVICE:[PROJD] 
DBG> SHOW SOURCE 

source directory search list for CTEST, 
match the exact source file version: 

[] 

SYSTEM::DEVICE:[PROJD] 

source directory list for all other modules, 
match the latest source file version: 

[PROJA] 

[PROJB] 

[PETER.PROJC] 


In this continuation of the previous example, the SET SOURCE 
/MODULE=CTEST command specifies that the debugger sh °uld search 
the current default directory ([]) and SYSTEM::DEVICE:[PROJD], in that 
order, for source files to use with the module CTEST. The /EXACT qualifier 
specifies that the search will try to locate the exact version of the CTES1 
source files found in the debug symbol table. 


3. 


DBG> SET SOURCE /EXACT 
DBG> SHOW SOURCE 

no directory search list in effect, 
match the exact source file 
DBG> SET SOURCE [JONES] 

DBG> SHOW SOURCE 

source directory list for all modules, 
match the exact source file version: 
[JONES] 

DBG> CANCEL SOURCE /EXACT 
DBG> SHOW SOURCE 

source directory list for all modules, 
match the latest source file version: 
[JONES] 


In this example, the SET SOURCE/EXACT command establishes a search 
method (exact version) that remains in effect for the SET SOURCE WON 
Thp CANCEL SOURCE/EXACT command not only cancels bLI 
also affects the SET SOURCE [JONES] 


command. 
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SET STEP 


Format 


Parameters 


Establishes default qualifiers (/LINE, /INTO, and so on) for the STEP command. 


SET STEP step-default[, ... ] 


BRANCH 
CALL 


INSTRUCTION 


step-default 

Specifies a default to be established for the STEP command. Valid keywords 
(which correspond to STEP command qualifiers) are as follows: 

Subsequent STEP commands are treated as STEP 
/BRANCH (step to the next branch instruction). 

Subsequent STEP commands are treated as STEP/CALL 
(step to the next call instruction). 

EXCEPTION Subsequent STEP commands are treated as STEP 

/EXCEPTION (step to the next exception). 

Subsequent STEP commands are treated as STEP 
/INSTRUCTION (step to the next instruction). 
fOn VAX processors, you can also specify one or more 
instructions ( opcodel , ...]). The debugger then steps to 
the next instruction in the specified list. 

tOn VAX processors, if you specify a vector 
instruction, do not include an instruction qualifier 
(/U, /V, /M, 10, or /l) with the instruction mnemonic. 

Subsequent STEP commands are treated as STEP/INTO 
(step into called routines) rather than STEP/OVER (step 
over called routines). When INTO is in effect, you can 
qualify the types of routines to step into by using the 
[NO]JSB, [NOJSHARE, and [NOJSYSTEM parameters 
or by using the STEP/[NO]JSB, STEP/[NO]SHARE, and 
STEP/[NO]SYSTEM command/qualifier combinations 
(the latter three take effect only for the immediate STEP 
command). 

If INTO is in effect, subsequent STEP commands are 
treated as STEP/INTO/JSB (step into routines called 
by a JSB instruction as well as those called by a CALL 
instruction). This is the default for all languages except 
JJI-dOL. 


INTO 


t JSB 


t NOJSB if i NT o i s i n effect, subsequent STEP commands are 

treated as STEP/INTO/NOJSB (step over routines called 
by a JSB instruction, but step into routines called by a 
CALL instruction). This is the default for DIBOL. 

tVAX specific ----- 
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SET STEP 


LINE 

(Default.) Subsequent STEP commands are treated as 

STEP/LINE (step to the next line). 

OVER 

(Default.) Subsequent STEP commands are treated as 

STEP/OVER (step over all called routines) rather than 

STEP/INTO (step into called routines). 

return 

Subsequent STEP commands are treated as STEP 
/RETURN (step to the return instruction of the routine 
that is currently executing—that is, up to the point just 
prior to transferring control back to the calling routine). 

$ SEMANTIC. 
EVENT 

Subsequent STEP commands are treated as STEP 
/SEMANTIC.EVENT (step to the next semantic event). 

This simplifies debugging optimized programs (see 

Chapter 13 for more information). 

SHARE 

(Default.) If INTO is in effect, subsequent STEP 
commands are treated as STEP/INTO/SHARE (step 
into called routines in shareable images as well as into 
other called routines). 

NOSHARE 

If INTO is in effect, subsequent STEP commands are 
treated as STEP/INTO/NOSHARE (step over called 
routines in shareable images, but step into other 
routines). 

SILENT 

Subsequent STEP commands are treated as STEP 
/SILENT (after a step, do not display the "stepped 
to ... " message or the source line for the current 
location). 

NOSILENT 

(Default.) Subsequent STEP commands are treated as 
STEP/NOSILENT (after a step, display the "stepped 
to ... " message). 

SOURCE 

(Default.) Subsequent STEP commands are treated as 
STEP/SOURCE (after a step, display the source line for 
the current location). Also, subsequent SET BREAK, 

SET TRACE, and SET WATCH commands are treated 
as SET BREAK/SOURCE, SET TRACE/SOURCE, and 

SET WATCH/SOURCE, respectively (at a breakpoint, 
tracepoint, or watchpoint, display the source line for the 
current location). 


$ Alpha specific 
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SET STEP 


NOSOURCE 


SYSTEM 


Subsequent STEP commands are treated as STEP 
/NOSOURCE (after a step, do not display the source line 
for the current location). Also, subsequent SET BREAK 
SET TRACE, and SET WATCH commands are treated 
as SET BREAK/NOSOURCE, SET TRACE/NOSOURCE 
and SET WATCH/NOSOURCE, respectively (at a 
breakpoint, tracepoint, or watchpoint, do not display 
the source line for the current location). 

(Default.) If INTO is in effect, subsequent STEP 
commands are treated as STEP/INTO/SYSTEM (step 
into called routines in system space (PI space) as well as 
into other called routines). 


NOSYSTEM 

t VECTOR. 
INSTRUCTION 

fVAX specific 


If INTO is in effect, subsequent STEP commands are 
treated as STEP/INTO/NOSYSTEM (step over called 
routines in system space, but step into other routines). 
On VAX processors, subsequent STEP commands are 
treated as STEP/VECTOR_INSTRUCTION (step to the 
next vector instruction). 


Description 


The SET STEP command establishes default qualifiers for subsequent STEP 
commands. The parameters that you specify in the SET STEP command have the 

X! T eS I s t =™T liflerS f0r the STEP The following parameters 

affect where the STEP command suspends execution after a step: 


BRANCH 

CALL 

EXCEPTION 

INSTRUCTION 


INSTRUCTION=(opcode[, . . . ]) (VAX only) 

LINE 

RETURN 

SEMANTIC.EVENT (Alpha only) 
VECTOR.INSTRUCTION (VAX only) 


executed Wmg parameters affect what out P ut is seen when a STEP command is 


[NOJSILENT 

[NOJSOURCE 


The following parameters affect what happens at a routine call: 
INTO 


[NOJJSB (VAX only) 
OVER 
[NO]SHARE 
[NOJSYSTEM 


You can override the current STEP defaults for the duration of a single STEP 
command by specifying other qualifiers. Use the SHOW STEP command to 
identify the current STEP defaults. 
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SET STEP 



Enabling screen mode by pressing PF1-PF3 enters the SET STEP NOSOU 
command as well as the SET MODE SCREEN command. Therefore any display 
of source code in output and DO displays that would result from a STEP 
command or from a breakpoint, tracepoint, or watchpoint being triggered is 
suppressed, to eliminate redundancy with the source display. 

On OpenVMS VAX systems, the STEP/OVER command may sometimes result 
in stepping into, not over, Fortran Run-Time Library routines. For more 
information, see Chapter 13. ♦ 

Related commands: 

SHOW STEP 

STEP 

Examples 

1. DBG> SET STEP INSTRUCTION,NOSODRCE 

This command causes the debugger to execute the program to the next 
instruction when a STEP command is entered, and not to display lines ot 
source code with each STEP command. 

2. DBG> SET STEP LINE,INTO,NOSYSTEM,NOSHARE 

This command causes the debugger to execute the program to the next 
line when a STEP command is entered, and to step into called routines in 
user space only. The debugger steps over routines in system space and m 
shareable images. 
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SET TASK 


Format 


muStof/pro^mt 8 ^ ° M ° r ^ ^ ° f “ Pr0gram <als ° calIed a 


SET TASK [task-spec[, ... ]] 


Parameters 


%ACTIVE_TASK 
%CALLER_TASK 

%NEXT_TASK 

%PRE VTOU S_TASK 
%VISIBLE_TASK 


Qualifiers 


task-spec 

Specifies a task value. Use any of the following forms: 

A task (thread) name as declared in the program, or a language expression 
that yields a task value. You can use a path name. expression 

A task ID (for example, %TASK 2), as indicated in a SHOW TASK display. 
One of the following task built-in symbols: 

The task that runs when a GO, STEP, CALL, or 
EXIT command executes. 

(Applies only to Ada programs.) When an accept 
statement executes, the task that called the entry 
associated with the accept statement. 

The task after the visible task in the debugger’s 
task list. The ordering of tasks is arbitrary but 
consistent within a single run of a program. 

The task previous to the visible task in the 
debugger’s task list. 

The task whose call stack and register set are the 
current context for looking up symbols, register 
values, routine calls, breakpoints, and so on. 

£ £ , /^Lr^M E ra MCE ni T* t th ; ,AL \ quaMw ' 

selected*” 


/ABORT 

Marks the specified tasks for termination. Termination occurs at the next 
llowable point after a specified task resumes execution. 

For Ada tasks, the effect is identical to executing an Ada abort statement fhr the 

ss =rssssst - - 

/ACTIVE 

STOP S G0 CALL e or‘EXlf e aC “ Ve ) ask - which is the ‘ask that runs when a 
’ w, CALL, or EXIT command executes. This causes a tn«t 

new active task and makes that task the visible task. The spedfied^m„s!T 
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be in either the RUNNING or READY state. When using /ACTIVE, you must 
specify one task. 

The SET TASK/ACTIVE command is supported for DEC Ada on VAX only. 

For DECthreads programs or DEC Ada on Alpha programs instead of SET TASK 
/ACTIVE use the SET TASK/VISIBLE command for query-type actions. Or, to 
gain control of execution, use a strategic placement of breakpoints. 

/ALL 

Applies the SET TASK command to all tasks. 

/HOLD 

SrTwhtrr'i spewed task is put on hold. The /HOLD qualifier puts a 
specified task on hold. 

Putting a task on hold prevents a task from entering the RUNNING state. A 
task put on hold is allowed to make other state transitions; in particular, it 
change from the SUSPENDED to the READY state. 

A task already in the RUNNING state (the active task) can continue to execute 
ts long as it remains in the RUNNING state, even though it is put on hold If the 
task leaves the RUNNING state for any reason (including expiration of a tim 
shce, Se sLing is enabled), it will not return to the RUNNING state until 

released from the hold condition. 

You can override the hold condition and force a task into the RUNNING state 
with the SET TASK/ACTIVE command even if the task is on noia. 

The /NOHOLD qualifier releases a specified task from hold. 

Sts^heVriority of a specified task to n, where n is a decimal integer from 0 to 15. 
This does not prevent the priority from later changing in the course of execution, 
for example, while executing an Ada rendezvous or DECthreads synchromza i 
event. This qualifier does not affect a task’s scheduling policy. 

Restore s^the priority of a specified task to the priority it had when it was created. 
Does not affect the scheduling priority of the task. 

/TIME_SLICE=t 

Supported for DEC Ada on VAX only. Sets the time-slice duration to the value 
l where / is a decimal integer or real value representing second^ The ^et valu 
overrides the time-slice value specified in the program, if any. To disable time 
slicing, use /TIME_SLICE=0.0. ♦ 

MakStiie specified task the visible task, which is the task whose call stack 
££££* ate the current context for looking up y**^-^"**, 
routine calls, breakpoints, and so on. Commands such as EXAMINE are ducted 
at the visible task. The /VISIBLE qualifier does not affect the active task. When 
using /VISIBLE, you must specify one task. 




SET TASK 


Description 


Examples 


SET command enables you to establish the visible task and the active 

indirectly™ ^ eX6CUtl ° n ° f tasks ’ and cause task state transitions, directly or 

To determine the current state of a task, use the SHOW TASK command The 
possible states are RUNNING, READY, SUSPENDED, and TERMINATED. 

Related commands: 

DEPOSIT/TASK 
EXAMINE/TASK 
SET BREAK/EVENT 
SET TRACE/EVENT 
SHOW TASK 


1. DBG> SET TASK/ACTIVE %TASK 3 

This command makes task 3 (task ID = 3) the active task. 

2. DBG> SET TASK %NEXT_TASK 

Sk th r« GXt task in the debu ^ er ’ s task list the visible 

task. (The /VISIBLE qualifier is a default for the SET TASK command.) 

I. DBG> SET TASK/HOLD/ALL 

DBG> SET TASK/ACTIVE ITASK 1 
DBG> GO 

DBG> SET TASK/ACTIVE %TASK 3 
DBG> STEP 


In this example, the SET TASK/HOLD/ALL command freezes the state of all 
tasks except the active task. Then, SET TASK/ACTIVE is used selectively 
(along with the GO and STEP commands) to observe the behavior of one or 
more specified tasks in isolation. 
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SET TERMINAL 

Sets the terminal-screen height or width that the debugger uses when it formats 
screen and other output. 

___ Note-- 

This command is not available in the DECwindows Motif interface to the 
debugger. 


Format 

SET TERMINAL 


Qualifiers 


Description 


/PAGEin 

Specifies that the terminal screen height should be set to n lines. You can use 
any value from 18 to 100. 

SecifteTthat the terminal screen width should be set to n columns. You can use 
anyvalue from 20 to 255. For a VT100-, VT200-, or VT300 senes temunal, n is 

typically either 80 or 132. 

The SET TERMINAL command enables you to define the portion of the screen 
that the debugger has available for formatting screen output. 

This command is useful with VT100-, VT200-, or VT300-series terminals where 
you can set the screen width to typically 80 or 132 columns It is also useful with 
workstations, where you can modify the size of the terminal-emulator window 
that the debugger uses. 

You must specify at least one qualifier, either /PAGE or /WIDTH. You can specify 
both. You must specify a value for each qualifier used. 

When you enter the SET TERMINAL command, all screen window definitions 
(deluding those created by the user) are automatically adjusted for the new 
screen dimensions. For example, RH1 changes dimensions proportionally to 
remain the top right half of the screen. 

Similarly, all "dynamic" displays are automatically adjusted to maintain their 
relative dimensions. By default, all predefined and user-defined displays are 
dvnamic If you have specified /NODYNAMIC in a DISPLAY command the 
display is no longer dynamic. In that case, the display does not automatically 
change dimensions with a SET TERMINAL command. 

DISPLAY command to redisplay the display within any window definition (you 
can also use keypad-key combinations, such as BLUE-MINDS, to enter predefined 

DISPLAY commands). 

Related commands: 

DISPLAY/[NO]DYNAMIC 

EXPAND 
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SET TERMINAL 


(SET,SHOW,CANCEL) WINDOW 
SHOW TERMINAL 

Example 

DBG> SET TERMINAL/WIDTH:132 

This command specifies that the terminal screen width be set to 132 columns. 
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SET TRACE 


Establishes a tracepoint at the location denoted by an address expression, at 
instructions of a particular class, or at the occurrence of specified events. 


Format 

SET TRACE [address-expression[, ... ]] 

[WHEN(conditional-expression)] 
[DO(command[; ...])] 


Parameters 


address-expression ,. , . ... 

Specifies an address expression (a program location) at which a tracepoint is 
to be set. With high-level languages, this is typically a line number, a routine 
name or a label, and can include a path name to specify the entity uniquely. 
More generally, an address expression can also be a memory address or a register 
and can be composed of numbers (offsets) and symbols, as well as one or more 
operators, operands, or delimiters. For information about the operators that you 
can use in address expressions, see the Address.Expressions help topic. 

Do not specify the asterisk (*) wildcard character. Do not specify an address 
expression with the following qualifiers: 


/ACTIVATING 

/BRANCH 

/CALL 

/EXCEPTION 

/INSTRUCTION 

/INSTRUCTION=(opcode[, . . . ]) (VAX only) 


/INTO 

/[NOIJSB (VAX only) 

/LINE 

/OVER 

/[NOISHARE 

/[NOISYSTEM 

/TERMINATING 

/VECTORJNSTRUCTION (VAX only) 


The /MODIFY and /RETURN qualifiers are used with specific kinds of address 
expressions. 

If you specify a memory address or an address expression whose value is not 
a symbolic location, check (with the EXAMINE command) that an instruction 
actually begins at the byte of memory so indicated. If an instruction does not 
begin at this byte, a run-time error can occur when an instruction including tha 
byte is executed. When you set a tracepoint by specifying an address expression 
whose value is not a symbolic location, the debugger does not verify that the 
location specified marks the beginning of an instruction. 
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Qualifiers 


On VAX processors, CALLS and CALLG routines start with an entry mask. ♦ 

conditional-expression 

Specifies a conditional expression in the currently set language that is to be 
evaluated whenever execution reaches the tracepoint. (The debugger checks 
the syntax of the expressions in the WHEN clause when execution reaches 
the tracepoint, not when the tracepoint is set.) If the expression is true, the 
ebugger reports that a tracepoint has been triggered. If an action (DO clause) 
is associated with the tracepoint, it will occur at this time. If the expression is 
false a report is not issued, the commands specified by the DO clause (if one was 
specified) are not executed, and program execution is continued. 

command 

Specifies a debugger command to be executed as part of the DO clause when trace 
action is taken. The debugger checks the syntax of the commands in a DO clause 
when it executes the DO clause, not when the tracepoint is set. 


/ACTIVATING 

t0 l muI 1 ti P rocess debugging configuration (when 
DBG$PROCESS has the value MULTIPROCESS). Causes the debugger to trace 

qualifier neW Pr ° CeSS comes under debugger control. See also the /TERMINATING 

/AFTERin 

Specifies that trace action not be taken until the nth time the designated 
tracepoint is encountered (n is a decimal integer). Thereafter, the tracepoint 
occurs every time it is encountered provided that conditions in the WHEN clause 

as SETTRACE TRACE/AFTER:1 command has the same effect 

/BRANCH 

Causes the debugger to trace every branch instruction encountered during 
program execution. See also the /INTO and /OVER qualifiers. 

/CALL 

Causes the debugger to trace every call instruction encountered during program 
execution, including the return instruction. See also the /INTO and /OVER 
qualifiers. 

/EVENT=event-name 

Causes the debugger to trace the specified event (if that event is defined and 

* thG TTl^t faCilityX If y ° U Specify an address expression with 
th^^’ the debugger t0 trace whenever the specified event occurs for 

f reSS expression - You cannot Specify an address expression with certain 
event names. 

useDFuS ^ aVaiIab if far programs that cal l Ada or SCAN routines or that 
use DECthreads services. To identify the current event facility and the associated 
event names, use the SHOW EVENT.FACILITY command. associated 

/EXCEPTION 

Causes the debugger to trace every exception that is signaled. The trace action 
occurs before any application-declared exception handlers are invoked. 
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As a result of a SET TRACE/EXCEPTION command, whenever your program 
generates an exception, the debugger reports the exception and resignals the 
exception, thus allowing any application-declared exception handler to execute. 

WheI R you"d°not specify an opcode, causes the debugger to trace every instruction 
encountered during program execution. 

/INSTRUCTION[=(opcode[, ...])] 

On VAX processors, if you specify one or more opcodes, causes the debugger to 
trace every instruction whose opcode is in the list. 

If you specify a vector instruction, do not include an instruction qualifier (/U, /V, 
/M, /0, or /l) with the instruction mnemonic. ♦ 

See also the /INTO and /OVER qualifiers. 


(Default.) Applies only to tracepoints set with the following qualifiers (that is, 
when an address expression is not explicitly specified): 


/BRANCH 

/CALL 

/INSTRUCTION 

/INSTRUCTION=(opcode[, . . . ]) (VAX only) 


/LINE 

/VECTOR.INSTRUCTION (VAX only) 


When used with those qualifiers, /INTO causes the debugger to trace the specified 
points within called routines (as well as within the routine in which execution is 
currently suspended). The /INTO qualifier is the default and is the opposite of 


/OVER. 

When using /INTO, you can further qualify the trace action with the /[NO]JSB, 
/[NOISHARE, and /[NO]SYSTEM qualifiers. 




/JSB 

/NOJSB 

On VAX processors, qualifies /INTO. Use with /INTO and one of the following 
qualifiers: 


/BRANCH 

/CALL 

/INSTRUCTION 
/INSTRUCTION=(opcode[, . . . ]) 
/LINE 

/VECTOR.INSTRUCTION 


The /JSB qualifier is the default for all languages e “ e P t DI ® 0L It 
debugger set tracepoints within routines that are called by the JSB or CALL 
instruction The /NOJSB qualifier (the DIBOL default) specifies that tracepoints 
not be set within routines called by JSB instructions. In DIBOL, application- 
declaredroutines are called by the CALL instruction and DIBOL run-t,me l.brary 
routines are called by the JSB instruction. ♦ 
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Alpha 


/LINE 

Causes the debugger to trace the beginning of each source line encountered 
during program execution. See also the /INTO and /OVER qualifiers. 

/MODIFY 

Causes the debugger to trace when an instruction writes to and changes the value 

:f v - r mdlca ted by a specified address expression. The address expression 
is typically a variable name. 

The SET TRACEMOmw X “““T* is equivalent to SET WATCH X DO(GO). 
SET WATCH^ CE/M0DI ^ Y C ° mmand °P erates und er the same restrictions as 

If you specify an absolute address for the address expression, the debugger might 
not be able to associate the address with a particular data object. In this case the 
debugger uses a default length of 4 bytes. You can change this length, however 
by settmg the type to either WORD (SET TYPE WORD, which changes the ’ 
default length to 2 bytes) or BYTE (SET TYPE BYTE, which changes the default 
Eg ™ ^ SET LONGWORD command resSL de&ut" 

/OVER 

Applies only to tracepoints set with the following qualifiers (that is, when an 
address expression is not explicitly specified): 

/BRANCH 

/CALL 

/INSTRUCTION 

/INSTRUCTION=(opcode[, . . . ]) (VAX only) 

/LINE 

/VECTOR_INSTRUCTION (VAX only) 

When used with those qualifiers, /OVER causes the debugger to trace the 
specified pomts only within the routine in which execution is currently suspended 

is the default led r ° Utmes) ' The /0VER qualifier is the opposite of/INTO (which 

/RETURN 

break ° n the return instruction of the routine associated 
J nf) h * he ® pe “ fied address expression (which can be a routine name, line number 
and so on). Breaking on the return instruction enables you to inspect the local ’ 
environment (for example, obtain the values of local variables) while the routine 

your arcWtecture te ^ ^ ^ l0Cal environment may differ depending on 

th + iS q . UaKfier Can ° nly be applied t0 routines oaHod with a 
CALLS or CALLG instruction; it cannot be used with JSB routines. ♦ 

On Alpha processors, this qualifier can be applied to any routine. ♦ 

c T an%llTvtrr eSS /°" Parameter “ an instruction address within a routine. It 
can simply be a routine name, in which case it specifies the routine start address 
However, you can also specify another location in a routine, so you can see only 
those returns that are taken after a certain code path is followed. 

A SET TRACE/RETURN command cancels a previous SET TRACE if you specify 
the same address expression. j v y 
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/SHARE (default) 

/NOSHARE „ „ . ... 

Qualifies /INTO. Use with /INTO and one of the following qualifiers: 

/BRANCH 

/CALL 

/INSTRUCTION 

/INSTRUCTION=(opcode[, . . . ]) (VAX only) 

/LINE 

/VECTORJNSTRUCTION (VAX only) 

The /SHARE qualifier permits the debugger to set tracepoints mthin shareable 
image routines as well as other routines. The /NOSHARE qualifier specifies that 
tracepoints not be set within shareable images. 

/SILENT 

Controls whether the "trace ..." message and the source line for the current 
location are displayed at the tracepoint. The /NOSILENT qualifier specifies that 
the message is displayed. The /SILENT qualifier specifies that the message and 
source line are not displayed. The /SILENT qualifier overrides /SOURCE. 

/SOURCE 

/NOSOURCE (default) . ... , . +v , 0 

Controls whether the source line for the current location is displayed at the 
tracepoint. The /SOURCE qualifier specifies that the source hne is displayed. 

The /NOSOURCE qualifier specifies that the source ^e is not displayed. The 

/SILENT qualifier overrides /SOURCE. See also the SET STE 

command. 

/SYSTEM (default) 

/NOSYSTEM „ „ . ... 

Qualifies /INTO. Use with /INTO and one of the following qualifiers. 

/BRANCH 

/CALL 

/INSTRUCTION 

/INSTRUCTION=(opcode[, . . . ]) (VAX only) 

/LINE 

/VECTORJNSTRUCTION (VAX only) 

The /SYSTEM qualifier permits the debugger to set tracepoints within system 
routines (PI space) as well as other routines. The /NOSYSTEM qualifier specifies 
that tracepoints not be set within system routines. 

Cause^the tracepoint to disappear after it is triggered (the tracepoint does not 
remain permanently set). 

(Default^ Causes the debugger to trace when a process does an image exit 
The debugger gains control and displays its prompt wh«.the last rmage.ofa 
one-process or multiprocess program exits. See also the /ACTIVATING qual . 
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/VECTORJNSTRUCTION 


Description 


On VAX processors, causes the debugger to trace every vector instruction 
encountered during execution. See also the /INTO and /OVER qualifiers. ♦ 


When a tracepoint is triggered, the debugger takes the following actions: 


1 . 

2 . 


Suspends program execution at the tracepoint location. 

If you specified /AFTER when you set the tracepoint, checks the AFTER 
count. If the specified number of counts has not been reached, execution is 
resumed and the debugger does not perform the remaining steps. 

3. Evaluates the expression in a WHEN clause, if you specified one when you 
set the tracepoint. If the value of the expression is false, execution is resumed 
and the debugger does not perform the remaining steps. 

4. Reports that execution has reached the tracepoint location by issuing a 
"trace ..." message, unless you specified /SILENT. 

5. Displays line of source code corresponding to the tracepoint, unless you 

specified /NOSOURCE or /SILENT when you set the tracepoint or entered a 
previous SET STEP NOSOURCE command. 

6 tracepoint ^ C ° mmands in a D0 clause > if you specified one when you set the 

7. Resumes execution. 

You set a tracepoint at a particular location in your program by specifying an 
address expression with the SET TRACE command. You set a tracepoint on 

SX SETTrIcf 68 ’ ClaSS 1 °p nStrU 1 C 1 ti0nS ’ ° r events ^ specifying a qualifier 
with the SET TRACE command. Generally, you must specify either an address 

expression or a qualifier, but not both. Exceptions are /EVENT and /RETURN. 

The /LINE qualifier sets a tracepoint on each line of source code. 

The foUowmg qualifiers set tracepoints on classes of instructions. Using these 
qualifiers and /LINE causes the debugger to trace every instruction of your 
program as it executes and thus significantly slows down execution: 

/BRANCH 

/CALL 

/INSTRUCTION 

/INSTRUCTION=(opcoc/e[, . . . ]) (VAX only) 

/RETURN 

/VECTORJNSTRUCTION (VAX only) 

The following qualifiers set tracepoints on classes of events: 

/ACTIVATING 
/EVENT =event-name 
/EXCEPTION 
/TERMINATING 

The following qualifiers affect what happens at a routine call: 

/INTO 

/[NOJJSB (VAX only) 

/OVER 
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Examples 


/[NOJSHARE 

/[NO]SYSTEM 

The following qualifiers affect what output is displayed when a tracepoint is 
reached: 


/[NOISILENT 

/[NOISOURCE 

The following qualifiers affect the timing and duration of tracepoints: 


/AFTER:n 

/TEMPORARY 

Use the /MODIFY qualifier to monitor changes at program locations (typically 
changes in the values of variables). 

If you set a tracepoint at a location currently used as a breakpoint, the breakpoint 
is canceled in favor of the tracepoint, and conversely. 

Tracepoints can be user defined or predefined. User-defined tracepoints are those 
that you set explicitly with the SET TRACE command. Predefined tracepoints, 
which depend on the type of program you are debugging (for example, Ada or 
multiprocess), are established automatically when you start the debugger, se 
the SHOW TRACE command to identify all tracepoints that are currently set. 
Any predefined tracepoints are identified as such. 

User-defined and predefined tracepoints are set and canceled independently. 

For example, a location or event can have both a user-defined and a predefined 
tracepoint. Canceling the user-defined tracepoint does not affect the predefined 
tracepoint, and conversely. 

Related commands: 


(ACTIVATE,DEACTIVATE) TRACE 
CANCEL ALL 
GO 

SET BREAK 

(SET,SHOW) EVENT_FACILITY 
SET STEP [NOISOURCE 
SET WATCH 

(SHOW,CANCEL) TRACE 


1. DBG> SET TRACE SUB3 

This command causes the debugger to trace the beginning of routine SUB3 
when that routine is executed. 


2. DBG> SET TRACE/BRANCH/CALL 

This command causes the debugger to trace every BRANCH instruction and 
every CALL instruction encountered during program execution. 


3. 


DBG> set trace/line/into/noshare/nosystem 

This command causes the debugger to trace the beginning of every source 
line, including lines in called routines (/INTO) but not in shareable image 
routines (/NOSHARE) or system routines (/NOSYSTEM). 
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4. DBG> SET TRACE/NOSOURCE TEST5ULINE 14 WHEN (X .NE. 2) DO (EXAMINE Y) 

This command causes the debugger to trace line 14 of module TEST5 when 

The /NOSmmrp' At r« e traCepoint ’ the EXAMINE Y command is issued. 
The /NOSOURCE qualifier suppresses the display of source code at the 

tracepoint. The syntax of the conditional expression in the WHEN clause is 
language-dependent. 

5. DBG> SET TRACE/INSTRUCTION WHEN (X .NE. 0) 

This command causes the debugger to trace when X is not equal to 0 The 
condition is tested at each instruction encountered during execution The 

dependent 6 C ° ndltl ° nal ex P ression in the WHEN clause is language- 

6. DBG> SET TRACE/SILENT SUB2 DO (SET WATCH K) 

This command causes the debugger to trace the beginning of routine SUB2 

unng execution At the tracepoint, the DO clause sets a watchpoint on 

I a " ab e , K - The /SILENT ( t uaIifier suppresses the "trace ..." message and 

wav settinir^ 'v, 3 ? ^ trace P° int - This sample shows a convenient 

way of setting a watchpoint on a nonstatic (stack or register) variable. A 

nonstatic variable is defined only when its defining routine (SUB2 in this 
case) is active (on the call stack). ’ 

7. DBG> SET TRACE/RETURN ROUT4 DO (EXAMINE X) 

CaUS ?l tl ? e debugger t0 trace the return instruction of routine 
KUU14 (that is, just before execution returns to the calling routine) At the 
tracepoint, the DO clause issues the EXAMINE X command. This example 

a con y ement way of obtaining the value of a nonstatic variable just 
before execution leaves that variable’s defining routine. 

8. DBG> SET TRACE/EVENT=TERMINATED 

This command causes the debugger to trace the point at which any task 
makes a transition to the TERMINATED state. ^ 
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SET TYPE 

Format 

Parameters 


Establishes the default type to be associated with program locations that do 
not have a symbolic name (and, therefore, do not have an assocmted compile 
generated type). When used with /OVERRIDE, it establishes the default type to 
be associated with all locations, overriding any compiler-generated types. 


SET TYPE type-keyword 


type-keyword 

Specifies the default type 

ASCIC 

ASCID 


ASCII:n 


to be established. Valid keywords are as follows: 

Sets the default type to counted ASCII string with a 
1-byte count field that precedes the string and gives 
its length. AC is also accepted as a keyword. 

Sets the default type to ASCII string descriptor. 

The CLASS and DTYPE fields of the descriptor are 
not checked, but the LENGTH and POINTER fields 
provide the character length and address of the 
ASCII string. The string is then displayed. AD is 
also accepted as a keyword. 

Sets the default type to ASCII character string 
(length n bytes). The length indicates both the 
number of bytes of memory to be examined and the 
number of ASCII characters to be displayed. If you 
do not specify a value for n, the debugger uses the 
default value of 4 bytes. The value n is interpreted in 


decimal radix. 


Sets the default type to counted ASCII string with a 
2-byte count field that precedes the string and gives 
its length. This data type occurs in PASCAL and 
PL/I. AW is also accepted as a keyword. 


ASCIZ 


Sets the default type to zero-terminated ASCII string. 
The ending zero byte indicates the end of the string. 
AZ is also accepted as a keyword. 


BYTE 

D.FLOAT 


Sets the default type to byte integer (length 1 byte). 
Sets the default type to D_floating (length 8 bytes). 
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DATE.TIME 

Sets the default type to date and time. This is a 
quadword integer (length 8 bytes) containing the 
internal representation of date and time. Values are 
displayed in the format dd-mmm-yyyy hh:mm:ss.cc. 
Specify an absolute date and time as follows: 


[dd-mmm-yyyy[:]] [hh:mm:ss.cc] 

$EXTENDED_FLOAT 

Sets the default type to IEEE X floating (length 16 
bytes). 

FLOAT 

tOn VAX processors, sets the default type to F 
floating (length 4 bytes). $On Alpha processors, sets 
the default type to IEEE T_floating (length 8 bytes). 

G_FLOAT 

Sets the default type to G_floating (length 8 bytes). 

t H_FLOAT 

Sets the default type to Hfloating (length 16 bytes). 

INSTRUCTION 

Sets the default type to instruction (variable length, 
depending on the number of instruction operands and 
the kind of addressing modes used). 

t LONG_FLOAT 

Sets the default type to IEEE S_Floating type (single 
precision, length 4 bytes). 

t LONG_LONG_FLOAT 

Sets the default type to IEEE T_Floating type 
(double-precision, length 8 bytes). 

LONGWORD 

Sets the default type to longword integer (length 4 
bytes). This is the default type for program locations 
that do not have a symbolic name (do not have a 
compiler-generated type). 

OCTAWORD 

Sets the default type to octaword integer (length 16 
bytes). 

PACKED:/! 

Sets the default type to packed decimal. The value of 
n is the number of decimal digits. Each digit occupies 
one nibble (4 bits). 

QUADWORD 

TYPE=(ezp ress/on) 

Sets the default type to quadword integer (length 8 
bytes). This might be advisable for debugging 64-bit 
applications. 

Sets the default type to the type denoted by 
expression (the name of a variable or data type 
declared in the program). This enables you to specify 
an application-declared type. 

TVAX specific - -- 

$Alpha specific 
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Qualifiers 


Description 


Alpha 


Examples 


$ S FLOAT Same as LONG_FLOAT. 

$ T FLOAT Same as LONG_LONG_FLOAT. 


Sets the default type to word integer (length 2 bytes). 
Same as EXTENDED_FLOAT. 


tAlpha specific 


WORD 
tX FLOAT 


Assochdes^the type specified with all program locations, whether or not they have 
a symbolic name (whether or not they have an associated compiler-generated 

type). 


When you use EXAMINE, DEPOSIT, or EVALUATE commands, the default 
types associated with address expressions affect how the debugger interprets and 
displays program entities. 

The debugger recognizes the compiler-generated types associated with symbolic 
address expressions (symbolic names declared in your program), and it interprets 
and displays the contents of these locations accordingly. For program locations 
that do not have a symbolic name and, therefore, no associated compiler- 
generated type, the default type in all languages is longword integer, which 
is appropriate for debugging 32-bit applications. 

For debugging applications that utilize the 64-bit address space, it might be 
advisable to use the SET TYPE QUADWORD command. ♦ 

The SET TYPE command enables you to change the default type assoaated 
with locations that do not have a symbolic name The SET TYPE/O VERR 
command enables you to set a default type for all program locations, both those 
that do and do not have a symbolic name. 

The EXAMINE and DEPOSIT commands have type qualifiers (/ASCII, /BYTE, 
/G_FLOAT, and so on) which enable you to override, for the duration o a sing e 
command, the type previously associated with any program location. 

Related commands: 

CANCEL TYPE/OVERRIDE 

DEPOSIT 

EXAMINE 

(SET,SHOW,CANCEL) RADIX 
(SET,SHOW,CANCEL) MODE 
SHOW TYPE 


1. DBG> SET TYPE ASCII:8 

This command establishes an 8-byte ASCII character string as the default 
type associated with untyped program locations. 
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SET TYPE 


2. DBG> SET TYPE/OVERRIDE LONGWORD 

Th , 1 ® command establishes longword integer as the default type associated 
with both untyped program locations and program locations that have 
compiler-generated types. 

3. DBG> SET TYPE D_FL0AT 

This command establishes D_Floating as the default type associated with 
untyped program locations. 


4. 


DBG> SET TYPE TYPE=(S_ARRAY) 


This command establishes the type of the variable S_ARRAY 
type associated with untyped program locations. 


as the default 


CD-231 



SET VECTOR_MODE (VAX Only) 


SET VECTOR_MODE (VAX Only) 


On VAX processors, enables or disables a debugger vector mode option. 

Applies to VAX vectorized programs. 

Format 

SET VECTOR_MODE vector-mode-option 

Parameters 

vector-mode-option 

Specifies the vector mode option. Valid keywords are as follows: 

SYNCHRONIZED Specifies that the debugger force automatic 

synchronization between the scalar and vector 
processors whenever a vector instruction is executed. 
Specifically, the debugger issues a SYNC instruction 
after every vector instruction and, in addition, an 
MSYNC instruction after any vector instruction that 
accesses memory. This forces the completion of all 
activities associated with the vector instruction that is 
being synchronized: 

• Any exception that was caused by a vector 
instruction is delivered before the next scalar 
instruction is executed. Forcing the delivery 
of a pending exception triggers an exception 
breakpoint or tracepoint (if one was set) or invokes 
an exception handler (if one is available at that 
location in the program). 

• Any read or write operation between vector 
registers and either the general registers or 
memory is completed before the next scalar 
instruction is executed. 

The SET VECTOR_MODE SYNCHRONIZED 
command does not issue an immediate SYNC or 
MSYNC instruction at the time it is issued. To force 
immediate synchronization, use the SYNCHRONIZE 
VECTOR_MODE command. 

NOSYNCHRONIZED (Default.) Specifies that the debugger not force 

synchronization between the scalar and vector 
processors except for internal debugger purposes. 

As a result, any synchronization is controlled entirely 
by the program, and the program runs as if it were not 
under debugger control. 
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SET VECTOR_MODE (VAX Only) 


Description 


Examples 


Vector mode options control the way in which the debugger interacts with the 
vector processor. For details about the SET VECTOR_MODE command see the 
parameter descriptions. 

Related commands: (SHOW,SYNCHRONIZE) VECTOR_MODE. 


2 . 


DBG> SET VECT0R_M0DE SYNCHRONIZED 

This command causes the debugger to force synchronization between the 
scalar and vector processors after each vector instruction is executed. 

DBG> SHOW VECT0R_M0DE 

Vector mode is nonsynchronized 

DBG> SET VECT0R_M0DE SYNCHRONIZED O 

DBG> SHOW VECT0R_M0DE 

Vector mode is synchronized 

DBG> STEP 0 

stepped to .MAIN.\SUB\%LINE 99 
99: WDIVD V1,V0,V2 

DBG> STEP © 

^SYSTEM-F-VARITH, vector arithmetic fault, summary=00000002 / 

, , , mask=00000004, PC-000002E1, PSL=03C00010 

Dre fnn° n unhandled exception preceding .MAIN.\SUB\%LINE 100 
100: CLRL R0 

DBG> 

The comments that follow refer to the callouts in the previous example: 

O The SET VECTOR.MODE SYNCHRONIZED command causes the 
debugger to force automatic synchronization between the scalar and 
vector processors whenever a vector instruction is executed. 

® C0 T m£ T d sus P ends Program execution on line 99, just before 

a WDIVD instruction is executed. Assume that, in this example, the 
instruction will trigger a floating-point divide-by-zero exception. 

© This STEP command executes the WDIVD instruction, which triggers 
the exception. The vector exception is delivered immediately because the 
e bugger is being operated in synchronized vector mode. 
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SET WATCH 

Establishes a watchpoint at the location denoted by an address expression. 

Format 

SET WATCH address-expression[, ... ] 

[WHEN(conditional-expression)] 

[DO(command[; ...])] 


Parameters 


Qualifiers 


address-expression ,. . . , . , • 

Specifies an address expression (a program location) at which a watchpoint is 

to be set. With high-level languages, this is typically the name of a P r °gr 
variable and can include a path name to specify the variable uniquely. More 
generally, an address expression can also be a memory address or a register 
Ld can be composed of numbers (offsets) and symbols, as well as one or more 
operators, operands, or delimiters. For information about the operators that you 
can use in address expressions, type HELP Address_Expressions. 

Do not specify the asterisk (*) wildcard character. 

SpedfieTa conditional expression in the currently set language; the expression 
is to be evaluated whenever execution reaches the watchpoint. (The debugger 
checks the syntax of the expressions in the WHEN clause when execu ion reaches 
the watchpoint, not when the watchpoint is set.) If the expression is true the 
debugger reports that a watchpoint has been triggered. If an action (DO clause) 
is associated with the watchpoint, it will occur at this time. If the expression 
false, a report is not issued, the commands specified by the DO clause (if one was 
specified) are not executed, and program execution is continued. 

Specifies*! debugger command to be executed as part of the DO clause when 
watch action is taken. The debugger checks the syntax of the commands in a DO 
clause when it executes the DO clause, not when the watchpoint is set. 


Specifies that watch action not be taken until the nth time the designated 
watchpoint is encountered (n is a decimal integer). Thereafter, the watchpoi 
occurs every time it is encountered provided that conditions in the WHEN c au 
are true. The SET WATCH/AFTER: 1 command has the same effect as bEi 

WATCH. 


Specifies that the debugger is to monitor a nonstatic variable by tracing 
instructions not only within the defining routine, but also withina^routine^tha 
is called from the defining routine (and any other such nested calls). The SEi 
WATCH/INTO command enables you to monitor nonstatic variables within called 
routines more precisely than SET WATCH/OVER-but the speed of execution 
within called routines is faster with SET WATCH/OVER. 
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SET WATCH 


Description 


/OVER 

Specifies that the debugger is to monitor a nonstatic variable by tracing 
instructions onty within the defining routine, not within a routine that is called 
by the defining routine. As a result, the debugger executes a called routine at 
normal speed and resumes tracing instructions only when execution returns to 

Zn SEmSS SET W AT cH, over command prov . iea faster 

ShT WATCH/INTO; but if a called routine modifies the watched variable 
execution is interrupted only upon returning to the defining routine. When you 
set watchpoints on nonstatic variables, SET WATCH/OVER is the default. 

/SILENT 

/NOSILENT (default) 

Controls whether the "watch ..." message and the source line for the current 
location are displayed at the watchpoint. The /NOSILENT qualifier specifies that 
he message is displayed. The /SILENT qualifier specifies that the messS and 
urce line are not displayed. The /SILENT qualifier overrides /SOURCE. 

/SOURCE (default) 

/NOSOURCE 

Controls whether the source line for the current location is displayed at the 

“ SP6CifieS ^ tHe ^ * displayed. 

/STTFNT S ° ?fi qUallfi f s Pfc ifies th «t the source line is not displayed. The 
olLENT qualifier overrides /SOURCE. See also the SET STEP [NOJSOURCE 
command. 

/STATIC 

/NOSTATIC 

o°fwWhr CeSSOr l T ableS J 0U t0 override the debugger’s default determination 
/STATTP ,T Clfied V ® nab v le (watchpoint location) is static or nonstatic. The 
ATIC qualifier specifies that the debugger should treat the variable as a 
static variable, even though it might be allocated in PI space. This causes the 
debugger to monitor the location by using the faster write-protection method 
rather than by tracing every instruction. The /NOSTATIC qualifier specifies that 
the debugger should treat the variable as a nonstatic variable, even though it 

Wtadn? ated ? P0 , spa< ?' and cames the debu ^ r to ‘he iTattn 

by tracing every instruction. Be careful when using these qualifiers. 

/TEMPORARY 

Causes the watchpoint to disappear after it is triggered (the watchpoint does not 
remain permanently set). 


When an instruction causes the modification of a watchpoint location, the 
debugger takes the following actions: 

Suspends program execution after that instruction has completed execution. 

If you specified /AFTER when you set the watchpoint, checks the AFTER 
count. If the specified number of counts has not been reached, execution 
continues and the debugger does not perform the remaining steps. 

Evalu ates the expression in a WHEN clause, if you specified one when you 

wntchpomt. If the value of the expression is false, execution continues 
nd the debugger does not perform the remaining steps. 


1 . 

2 . 

3. 
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SET WATCH 


4. Reports that execution has reached the watchpoint location ("watch of . . . ") 
unless you specified /SILENT. 

5. Reports the old (unmodified) value at the watchpoint location. 

6. Reports the new (modified) value at the watchpoint location. 

7 Displays the line of source code at which execution is suspended, unless you 
specified /NOSOURCE or /SILENT when you set the watchpoint or entered a 
previous SET STEP NOSOURCE command. 

8 Executes the commands in a DO clause, if you specified one when you set the 
watchpoint. If the DO clause contains a GO command, execution continues 
and the debugger does not perform the next step. 

9. Issues the prompt. 

For high-level language programs, the address expressions you specify withthe 
SET WATCH command are typically variable names. If you specify an abs 
memory address that is associated with a compiler-generated tpe, toe 'debugger 
symbolizes the address and uses the length in bytes associated with a yp 
to determine the length in bytes of the watchpoint location If you specifyan 
absolute memory address that the debugger cannot associate with a compiler-^ 
generated type, the debugger watches 4 bytes of memory, by default, begi g 
at the byte identified by the address expression. You can change this length, 
however by setting the type to either WORD (SET TYPE WORD, which changes 
the default length to 2 bytes) or BYTE (SET TYPE BYTE, which changes the 
default length to 1 byte). SET TYPE LONGWORD restores the default length of 

4 bytes. 

You can set watchpoints on aggregates (that is, entire arrays or records). A 
watchpoint set on an array or record triggers if any element of the array o 
record changes. Thus, you do not need to set watchpoints on individual array 
elements or^record components. Note, however, that you cannot set an aggregate 
watchpoint on a variant record. 

You can also set a watchpoint on a record component, on an individual array 
element or on an array slice (a range of array elements). A watehpoint set on an 
array slice triggers if any element within that slice changes. When setting the 
watchpoint, follow the syntax of the current language. 

The following qualifiers affect what output is seen when a watchpoint is reached: 

/[NOJSILENT 

/[NOISOURCE 

The following qualifiers affect the timing and duration of watchpoints: 

/AFTER:n 

/TEMPORARY 

The following qualifiers apply only to nonstatic variables: 

/INTO 

/OVER 

The following qualifier overrides the debugger’s determination of whether a 
variable is static or nonstatic: 

/[NO]STATIC 
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Static and Nonstatic Watchpoints 

The technique for setting a watchpoint depends on whether the variable is static 
or nonstatic. 

A static variable is associated with the same memory address throughout 

execution of the program. You can always set a watchpoint on a static variable 
throughout execution. 


A nonstatic variable is allocated on the call stack or in a register and has a value 
only when its defining routine is active (on the call stack). Therefore, you can set 
a watchpoint on a nonstatic variable only when execution is currently suspended 
within the scope of the defining routine (including any routine called by the 
defining routine). The watchpoint is canceled when execution returns from the 
e mng routine. With a nonstatic variable, the debugger traces every instruction 
to detect any changes in the value of a watched variable or location. 


Another distinction between static and nonstatic watchpoints is speed of 
execution. To watch a static variable, the debugger write-protects the page 
containing the variable. If your program attempts to write to that page, an access 
violation occurs and the debugger handles the exception, determining whether the 
watched variable was modified. Except when writing to that page, the program 
executes at normal speed. 


To watch a nonstatic variable, the debugger traces every instruction in the 
variables defining routine and checks the value of the variable after each 
instruction has been executed. Since this significantly slows execution, the 
debugger issues a message when you set a nonstatic watchpoint. 

As explained in the next paragraphs, /[NO]STATIC, /INTO, and /OVER enable 
you to exercise some control over speed of execution and other factors when 
watching variables. 


The debugger determines whether a variable is static or nonstatic by checking 
now it is allocated. Typically, a static variable is in PO space (0 to 3FFFFFFF, 
hexadecimal); a nonstatic variable is in PI space (40000000 to 7FFFFFFF) or' 
in a register The debugger issues a warning if you try to set a watchpoint on 
a variable that is allocated in PI space or in a register when execution is not 
currently suspended within the scope of the defining routine. 

The /[NOJSTATIC qualifiers enable you to override this default behavior. For 
example, if you have allocated nonstack storage in PI space, use /STATIC when 
setting a watchpoint on a variable that is allocated in that storage area. This 
enables the debugger to use the faster write-protection method of watching the 
location instead of tracing every instruction. Conversely, if, for example, you 
have allocated your own call stack in P0 space, use /NOSTATIC when setting a 
watchpoint on a variable that is allocated on that call stack. This enables the 
debugger to treat the watchpoint as a nonstatic watchpoint. 

You can also control the execution speed for nonstatic watchpoints in called 
routines by using /INTO and /OVER. 


On both Alpha and VAX processors, both static and nonstatic watchpoints are 
available. With static watchpoints, the debugger write-protects the page of 
memory m which the watched variable is stored. Static watchpoints, therefore 
would interfere with the system service itself if not for the debugger’s use of ’ 
system service interception (SSI). 
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Alpha 


If a static watchpoint is in effect then, through system service interception the 
debugger deactivates the static watchpoint, asynchronous traps (ASTs), and 
thread switching, just before the system service call. The debugger reactivates 
them just after the system service call completes, putting the watchpoint, Ab 
enabling, and thread switching back to their original state and, finally, checking 
for any watchpoint hits. This behavior is designed to allow the system service to 
run as it normally would (that is, without write-protected pages) and to prevent 
the AST code or a different thread from potentially changing the watchpointed 
location while the watchpoint is deactivated. Be aware of this behavior if, for 
example, your application tests to see if ASTs are enabled. 

System service interception is on by default, but on Alpha processors only, yon 
can disable interception prior to a debugging session by issuing the following 
command: 

$ DEFINE SSI$A0T0_ACTIVATE OFF 

To re-enable system service interception, issue one of the following commands: 

$ DEFINE SSI$AUTO_ACTIVATE ON 
$ DEASSIGN SSI$AUT0_ACTIVATE 

♦ 

Related commands: 

(ACTIVATE,DEACTIVATE) WATCH 

MONITOR 

SET BREAK 

SET STEP [NOjSOURCE 

SET TRACE 

(SHOW,CANCEL) WATCH 


Examples 

1. DBG> SET WATCH MAXCOUNT 

This command establishes a watchpoint on the variable MAXCOUNT. 

2 . DBG> SET WATCH ARR 
DBG> GO 

watch of SUBR\ARR at SUBR\%LINE 12+8 


old value: 


(1) 

7 

(2) 

12 

(3) 

3 

new value: 

(i) 

7 

(2) 

12 

(3) 

28 


break at SUBR\%LINE 14 
DBG> 

In this example, the SET WATCH command sets a watchpoint on the 
three-element integer array, ARR. Execution is then resumed with the GO 
command. The watchpoint triggers whenever any array element changes. In 
this case the third element changed. 
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3. DBG> SET WATCH ARR(3) 

This command sets a watchpoint on element 3 of array ARR (FORTRAN 
array syntax). The watchpoint triggers whenever element 3 changes. 

4. DBG> SET WATCH P_ARR [3:5] 

Thus command sets a watchpoint on the array slice consisting of elements 3 

to 5 of array P_ARR (Pascal array syntax). The watchpoint triggers whenever 
any of these elements change. wnenever 

5. DBG> SET TRACE/SILENT SUB2 DO (SET WATCH K) 

exam P le > vari able K is a nonstatic variable and is defined only when 
its defining routine, SUB2, is active (on the call stack). The SET TRACE 

execution The nnT^ T SUB2 ^ the tracepoint is triggered during 
r^TeleH u D ° C ? USe 8 a watch P° int on K - The watchpoint is then 
canceled when execution returns from routine SUB2. The /SILENT qualifier 

tracepoTT ^ " message and the dis P la y of source code at the 


6. DBG_1> SET WATCH ARR (1) 

DBG_1> SHOW WATCH 
watchpoint of PPL3\ARR(1) 

DBG_1> GO 

«DEBUG-I-WATVARNOWGBL, watched variable PPL3\ARR(1) 
has been remapped to a global section 

predefined trace on j^ivation at routine PPL3 in %PROCESS NUMBER 2 
preaetmea trace on activation at routine PPL3 in %PROCESS~numrfr ^ 

watch of PPL3\ARR(1, at PPL3ULINE 93 in ^PROCESS NUMBER 2~ 

93 •' ARR(l) = INDEX 

old value: 0 
new value: 1 

break at PPL3ULINE 94 in %PR0CESS NUMBER 2 


94: ARR(I) 

DBG_2> DO (SHOW WATCH) 

For %PROCESS_NUMBER 1 
watchpoint of PPL3\ARR(1) 
For %PROCESS_NUMBER 2 
watchpoint of PPL3\ARR(1) 
For %PROCESS_NUMBER 3 
watchpoint of PPL3\ARR(1) 
DBG 2> 


= I 

[global-section watchpoint] 
[global-section watchpoint] 
[global-section watchpoint] 


In this VAX example of a global section watchpoint, the SET WATCH 
command sets a watchpoint on element 1 of array ARR. Because ARR has 
yet been mapped to a global section, the SHOW WATCH command identifies 
the watchpoint as a conventional static watchpoint. 

After the GO command resumes execution, ARR is remapped to a global 
watchpoinf 16 Watchp ° mt 18 auto matically treated as a global section 

ftiTeTpT 2 and 3 C T e under debugger control > then the watchpoint is 
pr0Ce / s 2, interrupting execution. At this point, the SHOW 
WATCH command confirms that the watchpoint is visible from each 
process. 
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SET WINDOW 

Creates a screen window definition. 


Note 


This command is not available in the DECwindows Motif interface to the 
debugger. 


Format 


SET WINDOW 


window-name 
AT (start-line,line-count 
[.start-column,column-count]) 


Parameters 


SpecmesttiTname of the window you are defining If a window definition with 
that name already exists, it is canceled in favor of the new defimtio . 

SpSfies the starting line number of the window. This line displays the window 
title, or header line. The top line of the screen is line 1. 

SpeciteTthe number of text lines in the window not counting the 

The value must be at least 1. The sum of start-line and line-count must not 

exceed the current screen height. 

Snecifies^the starting column number of the window. This is the column at which 
£ tot character of the window is displayed. The leftmost column of the screen 

is column 1. 

Specifie^the*number of characters per line in the window. The value must be at 
least 1. The sum of start-column and column-count must not exceed the current 

screen width. 


Description 


A screen window is a rectangular region on the terminal screen through which 
you can view a display. The SET WINDOW command establishes a window 
Lfmitinn bv associating a window name with a screen region. You specify the 
“ on “glTn ^ma of a starting line and height (line count) and opttonally, 
a startingcolumn and width (column count). If you do not specify the starting 
co?^ and column count, the, default to column 1 and the current screen width. 

You can specif, a window region in terms of expressions that use the built-in 
symbols %PAGE and % WIDTH. 

You can use the names of any windows you have defined with the SET WINDOW 
command in a DISPLAY command to position displays on the screen. 
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Examples 


Window definitions are dynamic-that is, window dimensions expand and 

contract proportionally when a SET TERMINAL command changes the screen 
width or height. 

Related commands: 


DISPLAY 

(SHOW,CANCEL) DISPLAY 
(SET,SHOW) TERMINAL 
(SHOW,CANCEL) WINDOW 


2 . 


1. DBG> SET WINDOW ONELINE AT (1,1) 

This command defines a window named ONELINE at the top of the screen 
The window is one line deep and, by default, spans the width of the screen. 

DBG> SET WINDOW MIDDLE AT (9,4,30,20) 

This command defines a window named MIDDLE at the middle of the screen 
“To 13 4 lmeS deeP Starting at line 9 > and 20 columns wide starting 

DBG> SET WINDOW FLEX AT (%PAGE/4,%PAGE/2,%WIDTH/4,%WIDTH/2) 

co “ m and defines a window named FLEX that occupies a region around 

^p™ ddle th e screen and is defined in terms of the current screen height 
(%PAGE) and width (%WIDTH). g 


3. 
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SHOW ABORT_KEY 

Identifies the Ctrl-key sequence currently defined to abort the execution of a 
debugger command or to interrupt program execution. 

__ Note -- 

This command is not available in the DECwindows Motif interface to the 
debugger. 


Format 


SHOW ABORT_KEY 


Description 


By default, the Ctrl/C sequence, when entered within a debugging session, aborts 
the execution of a debugger command and interrupts program execution. e 
SET ABORT_KEY command enables you to assign the abort function to another 
Ctrl-key sequence. The SHOW ABORT.KEY command identifies the Ctrl-key 
sequence currently in effect for the abort function. 

Related commands: 

Ctrl/C 

SET ABORT_KEY 


Example 


DBG> SHOW AB0RT_KEY 
Abort Command Key is CTRL_C 
DBG> SET ABORTJCEY = CTRL_P 
DBG> SHOW ABORTJCEY 
Abort Command Key is CTRL_P 
DBG> 

In this example the first SHOW ABORT.KEY command identifies the default 
in tms examp , , , r TVl „ qprp ABORT KEY = CTRL P command 

abort command key sequence, Ctrl/C. Ihe bit I acu^.mi - 

assigns the abort-command function to Ctrl/P, as confirmed by the second SHOW 
ABORT_KEY command. 
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SHOW AST 


Indicates whether delivery of ASTs is enabled or disabled. 

Format 

SHOW AST 

Description 


Example 


disabW°TW T C ° mm f" d indlcat f whether delivery of ASTs is enabled or 
disabled. The command does not identify an AST whose delivery is pending The 

ivery of ASTs is enabled by default and with the ENABLE AST command The 
delivery of ASTs is disabled with the DISABLE AST command C ° mmand - The 

Related commands: (ENABLE,DISABLE) AST. 


DBG> SHOW AST 
ASTs are enabled 
DBG> DISABLE AST 
DBG> SHOW AST 
ASTs are disabled 
DBG> 

The SHOW AST command indicates whether the delivery of ASTs is enabled. 
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SHOW ATSIGN 


Identifies the default file specification established with the last SET ATSIGN 
command. The debugger uses this file specification when processing the execute 

procedure (@) command. 


Format 


SHOW ATSIGN 


Description 

Related commands: 

@ (Execute Procedure) 
SET ATSIGN 


Examples 


using DEBUG.COM 


1. DBG> SHOW ATSIGN 

No indirect command file default in effect, 

DBG> 

This example shows that if you did not use the SET ATSIGN command, the 
debugger assumes command procedures have the default file specification 
SYS$DISK:[ ]DEBUG.COM. 

2. DBG> SET ATSIGN USER: [JONES.DEBUG].DBG 

fnSreTcoSafd file default is USER: [JONES.DEBUG] .DBG 
DBG> 

In this example, the SHOW ATSIGN command indicates the default file 
specification for command procedures, as previously established with the SET 

ATSIGN command. 
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SHOW BREAK 


Displays information about breakpoints. 


Format 


Qualifiers 


SHOW BREAK 


/PREDEFINED 

Displays information about predefined breakpoints. 

/USER 

Displays information about user-defined breakpoints. 


Description 


Alpha 


Examples 


. di6plays informati °" about breakpoints that are 
ently set, including any options such as WHEN or DO clauses /AFTFR 

counts, and so on, and whether the breakpoints are deactivated ’ E ® 

action.) ’ * h h time the debugger takes break 

s SSSSSsSSSSF^^- 

Related commands: 

(ACTIVATE,DEACTIVATE) BREAK 
(SET,CANCEL) BREAK 


1. dbg> show break 

breakpoint at SUB1\L00P 
breakpoint at MAIN\MAIN+1F 

do (EX SUB1\D ; EX/SYMBOLIC PSL; GO) 
breakpoint at routine SUB2\SUB2 
/after: 2 
DBG> 

^ Ssr^nSrTusSSSiXir T' CUrre f y 

S“~ Uti ° n reaCheS SUB1XL00P ’ MAINVMAIN, and SUBDUE* 
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SHOW BREAK 


2. DBG> SHOW BREAK/PREDEFINED MnFNT Q EXCEPTION" 

predefined breakpoint on Ada event "DEPENDENTS_EXCEPT1UN 

predefined "breakpoint on Ada event -EXCEPIIOH.TERMINATED- 
for any value 
DBG> 

TUs command identifies the predeflned breakpoints that are currently set. 
The example shows two predefined breakpoints, which are associated wit 
Ida tasking exception events. These breakpoints are set automatically by the 
debugger for all Ada programs and for any mixed language program that 
linked with an Ada module. 
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Format 


Parameters 


Identifies the currently active routine calls. 


SHOW CALLS [integer] 


integer 


Description 




routSSt^eadTT the 

Any recursive mutae/T* 0 " “ CUrre "“>' S “ S P“«' 
CALLS command to ^Zn'^S^ " *" ” « "» SH0W 

«" the cal. 

executing routine the next line iHenffi •+ 6 m , e ldentlfies the currently 
the caller of the caller, and so on. *“ “ * he followin S “» identifies 

XCZaS^r^ZonT^h- Ca "!n‘ he SH ° W CALLS “mmand 
framed,, for i^Ii ^ZZttS? CTifX SSFcXSI T1 

fieTco^ CallS ’ 6ither ~ *- tonnina^l^tSi 

^ "’S to »• -luence 

££ the show 


Alpha 


“calf tamZ ZsZhVrZl” T ^ ^ ^ P-edure 

stored in the register set) or a ’n^fiff framt 'Procedure (with a call frame 

SHOW CAT T <? L a t j , l 1 frame P roc edure (without a call frame) 

^^r^^~^£XAl ph a 

The following information is provided for each line of the SHOW CALLS display 
' a3teriSk tott » “ » f a “Odule 

’ LT c°™% S^ n ZS ded the mo<We is set <the first Une 
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SHOW CALLS 




Alpha 


Examples 


Alpha 


suspended). 

. The value of the PC in the calling routine at the time that contro was 
transferred to the called routine. 

On VAX Drocessors the PC value is shown as a memory address rela ive 
the nearest preceding symbol value (for example, a routine) and also as 

absolute address. ♦ ,. , 

On Alpha processors, the PC is shown as a memory address relattve to 
first code address in the module and also as an absolute address. 

Related commands: 

SHOW SCOPE 
SHOW STACK 


i dbg> show calls 

module name routine name line 


SUB2 

*SUBl 

*MAIN 

DBG> 


SUB2 

SUBl 

MAIN 


5 

10 


rel PC 

00000002 

00000014 

0000002C 


abs PC 

0000085A 

00000854 

0000082C 


This cemmand displays information about the sequence of currently acttve 
procedure calls on a VAX system. ♦ 


2. DBG> SHOW CALLS . re ]_ pQ abs PC 

module name routine name in^ 00000000000002B8 00000000000203C4 

-^the above appears to be a null frame in JJ^J^o^SJ^^oSSoOOOOOOoSo^S 
*MAIN MAIN 0000000000000000 FFFFFFFF8255A1F8 

This example is on an Alpha system. No£«h* sections 
reported accordingly. ♦ 
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SHOW DEFINE 



Identifies the default (ADDRESS, COMMAND, PROCESS GROUP or VALUE) 
currently in effect for the DEFINE command. ’ ° r VALUi ^ 


Format 


SHOW DEFINE 


Description 


Example 


t T he e SE e TDE?T U N l F Uier f0r th ! ^ PINE COmmand is the <™ established with 
the SET DEFINE command. If you did not enter a SET DEFINE command the 
default qualifier is /ADDRESS. command, the 


MOU.S £££?* the DEFINE command ' the SHOW 
Related commands: 

DEFINE 

DEFINE/PROCESS.GROUP 

DELETE 

SET DEFINE 

SHOW SYMBOL/DEFINED 


DBG> SHOW DEFINE 

Current setting is: DEFINE/ADDRESS 


This command indicates that the DEFINE 
address. 


command is set for definition 


by 
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SHOW DISPLAY 


SHOW DISPLAY 


Identifies one or more existing screen displays. 

_Note -- 

This command is not available in the DECwindows Motif interface to the 
debugger. 


Format 

SHOW DISPLAY [display-name[, ... ]] 


Parameters 


dteplay name 0 f a display If you do not specify a name, or if you specify the 
a^rtekU^Twildcard diaracter by Itself, all display definitions are listed. .Y° u l'® n 
uscTthe wildcard within a display name. Do not specif, a display name wrth the 
/ALL qualifier. 


Qualifiers 


/ALL 

Lists all display definitions. 

/SUFFIX[=process-identifier-type] nnrtPRorFqs has 

Applies to a multiprocess debugging configuration /when D^ 
the value MULTIPROCESS). Appends a process-identifying suffix to a disp y 
name Use L qualifier only directly after a display name. The suffix denotes 
the visible process at the time the command was issued. 

The /SUFFIX qualifier is used primarily in command procedures when you specify 
display definitions or key definitions that are bound to display definitions. 

Use any of the following process-identifier-type keywords: 

PROCESSJSTAME The display-name suffix is the process name. 

PROCESS NUMBER The display-name suffix is the process number (as shown 

in a SHOW PROCESS display). 

PROCESS_PID The display-name suffix is the process identification 

number (PID). 

If vou specify /SUFFIX without a process-identifier-type keyword, the P rocess 
Sfier type used for the displayname suffix is, by default, the same as that 
used for tto prompt suffix (see the SET PROMPT/SUFFIX command). 


Description 


he SHOW DISPLAY command lists all displays according to their °£ d ® r . 
splay list. The most hidden display is listed first, and the display that is on top 

: the display pasteboard is listed last. 
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SHOW DISPLAY 


Example 


preach display, the SHOW DISPLAY command lists its name, maximum size 
screen window and display kind (including any debug command list) It also ’ 
.denies whether the display is removed from the pasteboard or is dynamic (a 

Chanda ™i:r at,ca " y adjusts its window dimensions if the screen size is 

changed with the SET TERMINAL command). 

Related commands: 

DISPLAY 

EXTRACT/SCREEN_LAYOUT 
(CANCEL) DISPLAY 
(SET,CANCEL,SHOW) WINDOW 
SHOW SELECT 


DBG> SHOW DISPLAY 

display SRC at HI, size = 64, dynamic 

Hi* (EXAMINE/SOURCE . %S00RCE SC0PE\%PC) 

display ];ns t at HI, size = 64, removed, dynamic 
kind INSTRUCTION (EXAMINE/INSTRUCTION 0\%PC) 

display OUT 2 s2' S - Z ® = fnn rem ° Ved ' dynamic ' kdnd = AGISTER 
disolav Fxqni^J 4 ^ S1Z6 ~_ 1 ^ 0, d y namic ' kin d = OUTPUT 

display PROMPT at Q S6 ^ize" ^ dynamiC ' kind = 00 (EXAMINE SUM) 
uispiay fkumpt at S6, size = 64, dynamic, kind = PROGRAM 

DISp LAY command lists all displays currently defined In this 

PROM^i they H 1I lJ 1 1Ude th ! 2 Ve P redefined displays (SRC, INST, REG, OUT and 
PROMPT) and the user-defined DO display EXSUM. Displays INST and RFC 

rdiT^ln^ P “ ** DISPLAY —“be^d 
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SHOW EDITOR 


SHOW EDITOR 


Indicates the action taken by the EDIT command, as established by the SET 
EDITOR command. 


Format 


SHOW EDITOR 


Description 


Related commands: 
EDIT 

SET EDITOR 


Examples 


1 DBG> SHOW EDITOR . 

The editor is SPAWNed, with command line 

"EDT/START_POSITION=(n,1)" 

DBG> 

In this example, the EDIT command spawns the EDT editor in a subprocess. 
The /START POSITION qualifier appended to the command hne mdica 
that theTditing cursor is initially positioned at the begmnmg of the line that 
is centered in the debugger’s current source display. 

2 DBG> SET EDITOR/CALLABLE_TPU 

DBG> SHOW EDITOR , . . Q „ Tpn „ 

The editor is CALLABLE_TPU, with command line TPD 

DBG> 

In this example, the SHOW EDITOR command indicates that the EDIT 
command invokes the callable version of the DEC Text Processing Utility 
(DECTPU). The editing cursor is initially positioned at the beginning 

source line 1. 
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SHOW EVENT_FACILITY 


47T4 


Format 


Identifies the current event facility and the associated event names. 

nppi fad l itieS are available for programs that call Ada routines or that use 
DJi»Cthreads services. 

routines P ™ Cessors ’ event facilities are also available for programs that call SCAN 


SHOW EVENT_FACILITY 


Description 


Example 


The current event facility (ADA, THREADS, or SCAN) defines the eventpoints 
that you can set with the SET BREAK/EVENT and SET TRACE/EVENT 
commands. 

Hie SHOW EVENT.FACIUTY command identifies the event names associated 
"T? ST ent event faciUt y- the keywords that you can soS 

command^^ ^^^ 0 ^^ BREAK/EVENT and (SET,CANCEL) TRACE/EVENT 

Related commands: 

(SET,CANCEL) BREAK/EVENT 
SET EVENT_FACILITY 
(SET,CANCEL) TRACE/EVENT 
SHOW BREAK 
SHOW TASK 
SHOW TRACE 


DBG> SHOW EVENT_FACILITY 
event facility is THREADS 

Jni S l, C «°tTfJ. and ident j fi ® s the current event facility to be THREADS (DECthreads) 
or SET ^ ^ ^ US6d SET BREAK/EVE NT 
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SHOW EXIT_HANDLERS 


SHOW EXIT_HANDLERS 

Identifies the exit handlers that have been declared in your program. 


Format 

SHOW exitjhandlers 


Description 


The exit handler routines are displayed in the order 
is, last in, first out). The routine name is displayed 
Otherwise, its address is displayed. The debugger s 
displayed. 


that they are called (that 
symbolically, if possible, 
exit handlers are not 


Example 

DBG> SHOW EXIT_HANDLERS 

exit handler at STACKS\CLEANUP 

DBG> 

This command identifies the exit handler routine CLEANUP, which is declared m 
module STACKS. 
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SHOW IMAGE 


Format 


program. inf0rmati ° n ^ ° r m ° re imagGS that are P art of your running 


SHOW IMAGE [image-name] 


Parameters 


Description 


image-name 

Specifies the name of an image to be included in the display. If you do not specify 

rTrTv y ° U SpeClfy the asterisk ( * > wildcard character by itself, all images^^ 
e listed. You can use the wildcard within an image name. 


Example 


The SHOW IMAGE command displays the following information: 

• Name of the image 

Start and end addresses of the image 

■ .r ™„ e ^: with 0,6 set image Mmmand a ° aded ^ 

Current image that is your debugging context (marked with an asterisk (*)) 
Total number of images selected in the display 

• Number of bytes allocated for the RST and other internal structures 

™ng^he^SIDEOTl d J| S f y f fa" of “ image totalled 

Zto regrom q nStead ' th ’ S C ° mmand '““P'aya only the process 

Related commands: 

(SET,CANCEL) IMAGE 
(SET,SHOW,CANCEL) MODULE 


DBG> SHOW IMAGE SHARE* 
image name 

*SHARE 
SHARE1 
SHARE2 
SHARE3 
SHARE4 

total images: 5 
DBG> 

Sth ?T and identWes aU ° fim ages whose names start 

SHARE2 are set. ^ 


set 

base address 

end address 

yes 

00000200 

OOOOOFFF 

no 

00001000 

000017FF 

yes 

00018C00 

000191FF 

no 

00019200 

000195FF 

no 

00019600 

0001B7FF 

bytes 

allocated: 33032 
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SHOW KEY 


SHOW KEY 


Displays the debugger predefined key definitions and those created by the 
DEFINE/KEY command. 


Note 


This command is not available in the DECwindows Motif interface to the 
debugger. 


Format 


SHOW KEY [key-name] 


Parameters 


S»cffle7a function key whose definition is displayed. Do not use the asterisk (*) 
wildcard character. Instead, use the /ALL qualifier. Do not specify a key nam 
with /ALL or /DIRECTORY. Valid key names are as follows: 


Qualifiers 


Key Name 

LK201 Keyboard 

VT100-type 

VT52-type 

PFl 

PFl 

PFl 

Blue 

PF2 

PF2 

PF2 

Red 

PF3 

PF3 

PF3 

Black 

PF4 

PF4 

PF4 


KP0-KP9 

Keypad 0—9 

Keypad 0-9 

Keypad 0-9 

PERIOD 

Keypad period (.) 

Keypad period (. 

) 

COMMA 

Keypad comma (,) 

Keypad comma (,) 

MINUS 

Keypad minus (-) 

Keypad minus (- 

-) 

ENTER 

Enter 

ENTER 

ENTER 

El 

Find 



E2 

Insert Here 



E3 

Remove 



E4 

Select 



E5 

Prev Screen 



E6 

Next Screen 



HELP 

Help 



DO 

Do 



F6-F20 

F6-F20 




Displays all key definitions for the current state, by default, or for the states 
specified with /STATE. 
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SHOW KEY 


Description 


Examples 


/BRIEF 

S& a “ wilh 3 k3y 

/directory 

^iflem lm ££££** keys have been defined - D ° “* 

/STATE=(state-name [,...]) 

/NOSTATE (default) 

sj^srstrai zr* 

qualifier displays key definitions for the current state only ® 


Keypad mode must be enabled (SET MODE KEVPA m l^f 

command. Keypad mode is enabW b“defaulf ’ ^ y ° U 03,1 USe ^ 

By default, the current key state is the "DEFAULT" state Ym, ~ ni , eU 
current state by using the SET KEY/ST ATT? m , change the 

causes a state change (that is a wfw °^ y prGSsing 3 key that 

STATE or /SET_OTATE) th DEFI NE/KEY/LOCK_ 

Related commands: 


DEFINE/KEY 
DELETE/KEY 
SET KEY 


1. DBG> SHOW KEY/ALL 

This command displays all the key definitions for the current state. 


; 


DBG> SHOW KEY/STATE=BLUE KP8 
GOLD keypad definitions: 

DBG> 8 " " SccoU '' To P" ("oecho, terminate,nolock) 


This command displays the definition for keypad key 8 in the BLUE state. 

DBG> SHOW KEY/BRIEF KP8 
DEFAULT keypad definitions: 

KP8 = "Scroll/Up" 

DBG> 

This command displays the definition for keypad key 8 in the current state. 
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SHOW KEY 


4 . DBG> show key/directory 
M0VE_G0LD 
M0VE_BLUE 
MOVE 
GOLD 

EXPAND_GOLD 

EXPAND_BLUE 

EXPAND 

DEFAULT 

CONTRACT_GOLD 

CONTRACT_BLUE 

CONTRACT 

BLUE 

DBO 

This command displays the names of the states for which keys have been 
defined. 
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SHOW LANGUAGE 


Format 


Example 


Identifies the current language. 


SHOW LANGUAGE 


Description 


n^nteTniT^GUArF 6 ' 1 W “ h ^ ® ET 

language is> by ***, the language 
Related command: SET LANGUAGE. 


DBG> SHOW LANGUAGE 
language: BASIC 
DBG> 


This command displays the name of the current language as BASIC. 


CD-259 




SHOW LOG 


SHOW LOG 


Indicates whether the debugger is writing to a log file and identifies the current 
log file. 


Format 


Description 


Examples 


SHOW LOG 

SYS$DISK:[ JDEBUG.LOG. 

Related commands: 

SET LOG 

SET OUTPUT [NOILOG 

SET OUTPUT [NO]SCREEN_LOG 


1 . DBG> SHOW LOG 

not logging to DEBUG.LOG 

DBG> 

This command displays the name of the current log:«e a; ^EBUG.LOG (the 
default log file) and reports that the debugger is not writing it. 

2 DBG> SET LOG PROG 4 
DBG> SET OUTPUT LOG 

DBG> SHOW LOG , T .„ 

logging to USER?:[JONES.WORKlPROG4.LOG 

DBG> . i 

i ^ qft T OG command establishes that the current log n e 
In this example, the bhl but* commanu OUTPUT LOG 

• "dtjhpa T OG Tin the current default directory). The b 
file PROG4.COM in your current default directory. 
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SHOW MARGINS 


SHOW MARGINS 


Identifies the current source-line margin settings for displaying 


source code. 


Note 


debugger. mant * “ ” 0t aVai ' aWe to ““ DEC '* i " d <"™ Motif interface to the 


Format 


SHOW MARGINS 


Description 


Examples 


SETMARf^TNq^ 11 settiags ar ® the margin settings last established with the 

SSL 3nd ' By defeult ’ if y ° U did not enter a S ET MARGINS 
» margin is set to 1 and the right margin is set to 255. 

Related command: SET MARGINS. 


1. DBG> SHOW MARGINS 

DBG> mar9in: 1 ' ri 9 ht margin: 255 

This command displays the default margin settings of 1 and 255. 

2. DBG> SET MARGINS 50 
DBG> SHOW MARGINS 

left margin: 1 , right margin: 50 
DBG> 

defau “ left ^° f 1 «*» —— 

3. DBG> SET MARGINS 10:60 
DBG> SHOW MARGINS 

DBG> margin: 10 ' right mar gin: 60 

This command displays both margin settings modified to 10 and 60. 
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SHOW MODE 



SHOW MODE 

Identifies the current debugger modes (screen or no screen, keypad or nokeypad, 


and so on) and the current radix. 


Format 

SHOW MODE 


Description 


The current debugger modes are the modes last established with the SET MODE 
J^mmand By defeult, if you did not enter a SET MODE command, the current 

modes are the following: 


DYNAMIC 

NOG.FLOAT (D_float) 

INTERRUPT 

KEYPAD 

LINE 

NOSCREEN 

SCROLL 

NOSEPARATE 

SYMBOLIC 


Related commands: 

(SET,CANCEL) MODE 
(SET,SHOW,CANCEL) RADIX 


Example 


5> SHOW MODE 

ies: symbolic, line, d_float, screen, scroll, keypad, 
dynamic, interrupt, no separate window 
put radix ‘.decimal 
i-rmt radix:decimal 


DBG> 

The SHOW MODE command displays the current modes 
output radix. 


and current input and 
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SHOW MODULE 


SHOW MODULE 


Format 


Parameters 


Displays information about the modules in the current image. 
SHOW MODULE [module-name] 


Qualifiers 


module-name 

in ?l displayIf y ° u d ° 

modules a re selected ^ 


Description 


/RELATED 

/NORELATED (default) 

SHOWMODULeTZ S ' ) Contr o* s whether the debugger includes, in the 

t^uIhTS^nKSett ‘ 8 rehted ™ «** 

sr- d,sp r r kted ™ duks - - 

(/NORELATED) no related^L* ** ^ ® XaCt reIationsh iP- By default 

specified are seLted) 68 "* SeleCted f ° r dis P la y My modules 

/SHARE 

/NOSHARE (default) 

any ^ariide^images tat wt^nSked^tt" 0 " M ° DULE ^ 

(/NOSHARE) no shareable image drfa “>‘ 

Se a SS e si3“mi?m/d e l Ch f arca “ e taage “ your pr0 ^ am - 

SHOW MODULE/SHARP mage modules" have the prefix SHARE$. The 

we., as “«S“srr“r e ' 11,686 “ e ,mage » - 

uni T ai symbois that ^ 

that image lorn S^Sr ^ ( ^ f gl ° baI) s ^ols * 
SET IMAGE and SHOW I^E^ommids " 3PS ^ ° f 1the newer 


more^module^ selected fo^spky^ 1 ^ 8 ^ m0Wing infor mation about one or 
• Name of the module. 

' c^dSrt n sa 1 me^ge WhiCh ““ n “ dUle “ »> ”>"dules are 
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SHOW MODULE 


Examples 


debugger’s run-time symbol table (RST). 

Space (in bytes) required in the RST for symbol records in that module. 
Total number of modules selected in the display. 

Number of bytes allocated for the RST and other internal structures (the 
amount of heap space in use in the mam debugger s process). 

___Note ---- 

The current image is either the main image (by d^auWor^the^m^ 
established as the current image by a previous SET IMAGE comman 


For information specific to Ada programs, see the Language ADA help topic. 

Related commands: 

(SET,SHOW,CANCEL) IMAGE 
SET MODE [NOIDYNAMIC 
(SET,CANCEL) MODULE 
(SET,SHOW,CANCEL) SCOPE 
SHOW SYMBOL 


symbols size 


yes 

no 


432 

280 


2. bytes allocated: 2740. 


DBG> SHOW MODULE 
module name 

TEST 

SCREEN_IO 

total PASCAL modules 
DBG> 

t t-u- arrmlo thp SHOW MODULE command, without a parameter, 

module TEST has been set, but module SCREEN.IO tias not. 

DBG> SHOW MODULE F00, MAIN,SUB* 
module name symbols 

yes 
no 
no 
no 


language 

size 

MACRO 

432 

fortran 

280 

fortran 

164 

fortran 

204 


4. bytes allocated: 60720. 


FOO 
MAIN 
SUBl 
SUB2 

total modules 

DBG> . , , 

T 4-h.- TYirdp thp SHOW MODULE command displays information about 

source language. 
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SHOW MODULE 


3. DBG> SHOW MODULE/SHARE 
module name 

F00 
MAIN 

SHARESDEBUG 
SHARE$LIBRTL 
SHARE$MTHRTL 
SHARE$SHARE1 
SHARE$SHARE2 

total modules: 17. 

DBG> SET MODULE SHA^orwiu,/ 

DBG> SHOW SYMBOL * IN SHARE$SHARE2 

£e mL e 27\ the SH ° W M0D ULE/SHAEE command identifies all of 
names of Uie sh^«hi rrent ge a " d ° f the sh areable images (the 

MODULE SHaShAKE?™ ^ P a ! d f * SHARE »- The SET 
SHARE$SHARE2 $ t£sH 0W SYMBOL ™ 4116 shar « able module 
symbols defined in ttTSSsS? '"'"“ Sal 


symbols 

language 

size 

yes 

MACRO 

432 

no 

FORTRAN 

280 

no 

Image 

0 

no 

Image 

0 

no 

Image 

0 

no 

Image 

0 

no 

Image 

0 

bytes allocated: 162280. 
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SHOW OUTPUT 


SHOW OUTPUT 


Identifies the current output options. 


Format 


Description 


Example 


SHOW OUTPUT 

The current output options are the options last estabhshed wittthe ^ 

Related commands: 

SET LOG 

SET MODE SCREEN 
SET OUTPUT 


dbg> show output 

noverifv, torininalf scr66n_log^ a 

logging to USER$:[JONES.WORK]DEBUG.LOG;9 

DBG> 

This command shows the following current output options: 

• Debugger commands read from debugger command procedures are not ec oe 
on the terminal. 

• Debugger output is being displayed on the terminal. 

. The debugging session is being logged to the log file 

USER$:[JONES.WORK]DEBUG.LOG;9. 

. The screen contents are logged as they are updated in screen mode. 
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SHOW PROCESS 


Format 


Parameters 


SlTmmOT™appl"e s a ^pSy mult “'T?* under d « b "«8»r control. 
DBG$PROCESS has the value MmSSltOCES®! gging “Nation (when 


SHOW PROCESS [process-spec[, ... ]] 


process-spec 

form?" 3 Pr ° CeSS CUrrently under debugger control. Use any of the following 


[%PROCESS_NAME] proc-name 


The process name, if that name 
contains no space or lowercase 
characters. The process name can 
include the asterisk (*) wildcard 
character. 

The process name, if that name 
contains space or lowercase 
characters. You can also use 

apostrophes (') instead of quotation 
marks ("). 

The process identification number 
a hexadecimal number). 

The number assigned to a process 
when it comes under debugger 
control. Process numbers appear 
in a SHOW PROCESS display. 

A symbol defined with the DEFINE 
/PROCESS_GROUP command to 
represent a group of processes. 

Do not specify a recursive symbol 
definition. 

The process after the visible process 
m the debugger’s circular process 
list. 

The process previous to the visible 
process in the debugger’s circular 
process list. 

The process whose call stack, register 
set, and images are the current 
context for looking up symbols, 
register values, routine calls, 
breakpoints, and so on 

ssi k rjr ldcard character ° r •*» /all «. 

do not spa If ^ 

process is selected. 0r dJNUJHOLD, the visible 


[%PROCESS_NAME] « proc-name 


%PROCESS_PID proc-id 

%PROCESS_NUMBER proc-number 
(or %PROC proc-number) 


proc-group-name 


%NEXT_PROCESS 


%PREVIOUS_PROCESS 

%VISIBLE_PROCESS 
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SHOW PROCESS 


Qualifiers 


Description 


Selects all processes known to the debugger for display. 

(Default.) Displays only one line of information for each process selected for 
display. 

/[NO]DYNAMIC command. 

Displays maximum information for each process selected for display. 

/HOLD 

^Crises that are on hold, or presses that are not on hold for 
display. ., Tf 

ITl^s^^ 

are not on hold. . 

If you specify both /HOLD “Sdt display 

(the e qualifier e S pecified last on the command line does not override the other). 

(Default). Selects the visible process for display. 

The SHOW PROCESS command displays information about specified processes 
and any images running in those processes. 

debugging a program that uses vector instructions. 

!E*uSer r co^A p n ro a ce S ” cfn noton^a^inl SHOW PROCESS 
dSay if it 5 terminated through an EXIT or QUIT command. 

By default (/BRIEF), one line of information is displayed for each process, 

including the following: 

. The process number assigned by the debugger. A ^mt^deT 

sequentially, starting with process 1, to ^ EXIT q UIT comma nd, 

r^rr^ a ^~d=T»uSfi. ^ 

processls^marked with an asterisk < *) in the leftmost column). 

• The process name. 
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SHOW PROCESS 


^ mand‘ he Pr0C<!SS haS bee ” P1,t “ “ with a SET ™>CESS/HOLD 
The current debugging state for that process. (See Table CD-2 ) 

' s“r„'Z^ if " at is 



Break 

Break on branch 
Break on call 
Break on instruction 
Break on lines 
Break on modify of 
Break on return 
Exception break 
Exception break preceding 
Interrupted 


Step 

Step on return 
Terminated 


Trace 

Trace on branch 
Trace on call 
Trace on instruction 
Trace on lines 
Trace on modify of 
Trace on return 
Exception trace 
Exception trace preceding 
Unhandled exception 
Watch of 


Execution was interrupted in that process 
either because execution was suspended in 
another process, or because the user interrupted 
program execution with the abort-key sequence 
(by default, Ctrl/C). 

A STEP command has completed. 

The image indicated has terminated execution 
but the process is still under debugger control, 
erefore, you can obtain information about the 
and lts P roc ess. You can use the EXIT or 
(qJUIT command to terminate the process. 

A tracepoint was triggered. 


An unhandled exception was encountered. 
A watchpoint was triggered. 

COmmand ^ additi0nal about 

Related commands: 

CONNECT 

Ctrl/C 

define/process_group 
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SHOW PROCESS 


Examples 


EXIT 

QUIT 

SET PROCESS 


DBG 2> SHOW PROCESS 
Number Name Hold State 

* 2 WTA3: HOLD break 

DBG 2> “ 


Current PC 
SCREEN\%LINE 47 


DBG _2 > t . 

Bv default the SHOW PROCESS command displays one hne of in orma ion 

SCREEN. 

DBG_2> SHOW PEOCESS/FULL SPEEVI0 0 S_PR0CESS ^ ^ 

Hold 6S NO nU Visible process: NO 

Current PC: TEST_VALVES\%LINE 153 

i?:s m 

Current/Base priority: 5/4 Terminal: VTA79. 

Image name: USER$:[JONES.PR0G1]TEST_VALVES.EXE;31 


0 


00:03:17.17 

14894 

6956 

7 

200 

Yes 

Yes 


Elapsed CPU time: 

Buffered I/O Count 
Direct I/O Count: 

Open file count: 

Enqueue count: 

Vector capable: 

Vector consumer: 

Fast Vector context switches: 0 

Current working set size: 1102 

Current working set extent: 12288 
Peak working set size: 4955 

Current virtual size: 255 

Page faults: 41358 

Active ASTs: 

Event flags: 

DBG 2> 


CPU Limit: Infinite 

Remaining buffered I/O quota: 
Remaining direct I/O quota: 
Remaining open file quota: 
Remaining enqueue quota: 


80 

40 

43 

198 


Vector CPU time: 00:00:00.00 

Slow Vector context switches: u 

Working set size quota: 

Maximum working set extent: i “8 

Maximum authorized working set: 1304 

Peak virtual size: ibi ° 


FF800000 60000003 


Remaining AST Quota: 
Event flag wait mask: 


27 

7FFFFFFF 


The SHOW PROCESS/FULL %PREVIOUS_PROCESS command toplays the 
ma X fmum level of information aboutthe previous process m the cupular list 
of processes (process number 1, in this case). 

DBG 2> SHOW PROCESS %PROCESS_NAME TEST_3 
Number Name Hold State ^ TEST ^ UT4 \ C0UNT 

7 TESl__o TEST_3\%LINE 54 

DBG - 2> 

This SHOW PROCESS command displays one hne of mformation a p ^ 0U nT 
process TEST_3. The image is suspended at a watchpomt of variable COUNT. 
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SHOW PROCESS 


4. DBG_2> SHOW PROCESS/DYNAMIC 

^" a “ lc P r °cess setting is enabled 
DBG 2> 

This command indicates that dynamic process setting is enabled. 
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SHOW RADIX 


SHOW RADIX 


Format 


Identifies the current radix for the entry and display of integer data or, if you 
specify /OVERRIDE, the current override radix. 


SHOW RADIX 


Qualifiers 


/OVERRIDE 

Identifies the current override radix. 


Description 




Alpha 


The debugger can interpret an* ******“T 
dlS d onn”t“”he’ radix last established with the SET RADIX 
command. 

If you did not enter a SET RADIX command, the default radix for both data entry 
and display is decimal for most languages. 

On VAX processors, the exceptions are BUSS and MACRO-32, which have a 

default radix of hexadecimal. ♦ 

On Alpha processors, the exceptions are BUSS, MACRO-32, and MACRO-64, 
which have a default radix of hexadecimal. ♦ 

SET RADIX/OVERRIDE command, the override radix is non . 

Related commands: 

DEPOSIT 

EVALUATE 

EXAMINE 

(SET,CANCEL) RADIX 


Examples 


i. 


dbg> show radix 

input radix: decimal 
output radix: decimal 
DBG> 


2 . 


DBO 

This command identifies the input radix and output radix as decima . 

dbg> set radix/override hex 

DBO SHOW RADIX/OVERRIDE 

output override radix: hexadecimal 

DBO 

In this — ‘he SET ^“^^Ern^rrdfites 
S^ve^tr™: means that commands such as EXAMINE display all 
data as hexadecimal integer data. 
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SHOW SCOPE 


SHOW SCOPE 


Format 


Description 


Identifies the current scope search list for symbol lookup. 


SHOW SCOPE 


Examples 


r° 18 * ha ‘ ~ 

SETS™rZLrrB^ ^fu cUdnotmterl d 

the current scope search list is 0,1,2, ... , n . SC0PE command, 

p“&„„"h SS^r k w f t ou '; 

caller 

scope n, the debugger searches thp roof stacK > 11 x 1S n ot found in 

is, all set “^ b,e <RS “ 

£ S "lUrack d Se al sSo^SCOra S Z fTf T™* to re P"->‘ * -tine 
represented by ie fn^er" Se dl8P ‘ ayS name ° f the 

Related commands: (SET,CANCEL) SCOPE. 


DBG> CANCEL SCOPE 
DBG> SHOW SCOPE 
scope: 

o [ = eightqueens\trycol\removequeen 

1 [ - EIGHTQUEENS\TRYCOL ], 

2 [ = EIGHTQUEENS\TRYCOL 1 ], 

3 [ = EIGHTQUEENS\TRYCOL 2 ], 

4 [ = EIGHTQUEENS\TRYCOL 3 ], 

5 [ = EIGHTQUEENS\TRYCOL 4 ], 

6 [ = EIGHTQUEENS ] 

DBG> SET SCOPE/CURRENT 2 
DBG> SHOW SCOPE 


scope 

0 

1 

* 2 

3 

4 

5 

6 

DBG> 


= EIGHTQUEENS\TRYCOL\REMOVEQUEEN ] 
[ = eightqueens\trycol ], 

[ = EIGHTQUEENS\TRYCOL 1 ], 

[ = EIGHTQUEENS\TRYCOL 2 ], 

[ = EIGHTQUEENS\TRYCOL 3 ], 

[ = EIGHTQUEENS\TRYCOL 4 ], 

[ = EIGHTQUEENS ] 
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r,,, patsTPFT SCOPE command restores the default scope search list, 

Ihich is displayed by the (first) SHOW SCOPE command^ In this -ample, 

e r) i0 " ^“cTrYCO 

0 Y « oTL routine in which elution is 
The SET SCOPE/CURRENT command resets the/ ^tain Sutton 

command indicates that the scope search list now starts wrth scope 2. 

dbg> SET SCOPE 0,STACKS\R2,SCREEN_IO,\ 

dbg> show scope 

scope: 

0, [= TEST ], 

STACKS\R2, 

SCREEN_IO, 

\ 

DBG> . 

, . l +v,a qpt SCOPE command directs the debugger to look tor 

(denoted by the global scope (\ )). The SHOW the 

shoTs% s ^^^ r ch list is in effect or you 

have entered a SET SCOPE/CURRENT command. 





SHOW SEARCH 


Format 


Description 


currently in'effete ™ ENTIFIER or /STRI NG) 

SHOW SEARCH 


Example 


£ “iSSSHri ■s *■» *** «-»»- 

SEARCH command, the default ^ 

Related commands: 

SEARCH 

(SET,SHOW) LANGUAGE 
SET SEARCH 


as a string 
as an identifier 
as an identifier 


DBG> SHOW SEARCH 

fot next oc “ tr »“' 

DBG> SHOW SEARCH 

smssttir* £ " occurt<,nce ’ 

DBG> SHOW SEARCH 

search settings: search for all occurrences, 

££ SKS f y ^a" HhTd" r isplays the K default -*«■ 

displays the next occurrence oFthe strin “ SearCheS f ° r a " d 

that 11,6 «"■»- “ *» 

, 1 “ * » 

.eitlrnr side hy a d-SSSSS “ 
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SHOW SELECT 



SHOW SELECT 


Identifies the displays currently selected for eachirfttj display attributes: « 
innut. instruction, output, program, prompt, scroll, and sou . 


____ Note --- 

This command is not available in the DECwindows Motif interface to the 
debugger. _ 


Format 

SHOW SELECT 


Description 


The display attributes have the following properties: 

. A display that has the error attribute displays debugger diagnostic 
messages. 

. A display that has the input attribute echoes your debugger input. 

“hen you enter an EXAMINE/INSTRUCTION command. 

. A display that has the output attribute displays any debugger output that 
is not directed to another display. 

* 

' f np t P Cu"orfy tb r e°p m ROM"ay cltav^pSKSuS. 

. A display that has the scroll attribute is the default display for the 
SCROLL, MOVE, and EXPAND commands. 

a TYPE or EXAMINE/SOURCE command. 

RAlatfid commands: 


SELECT 
SHOW DISPLAY 
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SHOW SELECT 


Example 


DBG> SHOW SELECT 
display selections: 
scroll = SRC 
input = none 
output = OUT 
error = prompt 
source = SRC 
instruction = none 
program = PROMPT 
prompt = PROMPT 

DBG> 


T ^HOW SELECT command identifies 
of the display attributes. These selections 


the displays currently selected for 
are the defaults for languages. 


each 


CD-277 




SHOW SOURCE 


SHOW SOURCE 

Identifies the source directory search lists and search methods currently 


Format 


Qualifiers 


Description 


SHOW SOURCE 


Apples mainly to Ada programs.) Identifies the search list to be used during 
execution of the debugger’s EDIT command. 

_ 01?rr cnTTRrF/MODULE=moduZe-name command establishes a source 

The SET SOURCE/Muuui^ muuu SOURCE command 

directory search list for a particu arm • dl not explicitly mentioned 
establishes a source directory search list for annotates notP ^ ^ 

• o ctt <?DTTRCE/MODULE=mo<iMie-name command, vynen y . 

Tse cemm°a"0W SOURCE identifies the soume drrectory search hst 

associated with each search category. 

If a source directory search list has not been established by using the SET 

SOURCE or SET f in effect. 

SOURCE command indicates that no direct y game directory 

In this case the debugger^pects ch ecks that the version number 

r tL”^TL“a d tr file match the —ion in the 
debugger’s symbol table). 

The /EDIT qualifier is needed whenthe files * 

are different from the files to be edi e y^* g H ow SOURCE command 

the case with Ada programs. For Ada.programs• «“f ied .. ^ ffle s 

identifies the search list of filescommand identifies the 
in Ada program libraries); the bUOW d 

search list for the source files you edit when using 

For information specific to Ada programs, type HELP Language ADA. 

Related commands: 

(SET,CANCEL) SOURCE 
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SHOW SOURCE 


Examples 


2 . 


DBG> SHOW SOURCE 

no directory search list in effect 

ma ' :c ^ ^test source file version 
D D BG> SrSV PR0JAUPROJB, ' DISK; [PETER.PROJC] 

S0Ur mtch r the°rr Se f Ch liSt for 311 m °dules, 

1 L^T» atest SOUrce file version: 

[PROJA] 

[PROJB] 

DISK:[PETER.PROJC] 

DBG> 

debugger searches for the latest version of foura filt ' y ' 

"■ 0ISKS2: [PROOD] 

source directory search list for CTEST 
match^the exact source file version: 

DISK$2:[PROJD] 

SS2 Jffi version- 0t ^ er 

[PROJA] 

[PROJB] 

DISK:[PETER.PROJC] 

DBG> 

the current S6arch 

debug symbol table. ^ source files found in the 
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SHOW STACK 


SHOW STACK 

Displays information on the currently active routine calls. 


Format 


SHOW STACK [integer] 


Parameters 


Description 




Alpha 


asssatssKSSSSSSa 

sHSriSt'r'rrJ 

arguments. 

On VAX processors, each routine invocation results in a call frame on the call 
stack. ♦ 

On Alpha processors, aroutine invocation 

(with a coll frame on the stock), a eg^r ^ a ^ frame ). 

stored in the register set), or three- stack frame procedures, 

p— s <*• the ^ example 

below.) ♦ 

Related command: 

SHOW CALLS 


Examples 



i. 


dbg> show stack 

stack frame 0 (2146814812) 


condition handler: 
SPA: 

S: 

mask: 

PSW: 

saved AP: 
saved FP: 
saved PC: 
saved R2: 
argument list: (1) 


0 

0 

0 

a M<R2> 

0000 (hexadecimal) 

7 

2146814852 

EIGHTQUEENSULINE 69 
0 

EIGHTQUEENS\%LINE 68+2 


CD-280 





SHOW STACK 


Alpha 


stack frame 1 (2146814852) 

condition handler: SHARE$PASRTL+888 
SPA: o 

S: o 

mask: 

PSW: 

saved AP 


DBG> 


saved FP 
saved PC 


none saved 

0000 (hexadecimal) 

2146814924 

2146814904 

SHARE$DEBUG+667 


DBG> SHOW STACK 
invocation block 0 

FP: 000000007F907AD0 

Detected what appears to be a NULL frame 

NULL ProoedurrDescrlntJ^/nn^nnnnnftA^?^ context as their caller 


-~ V OCULlUll uu 

(0000000000010050)• 
3089 

PDSC$K KIND FP STACK 
0000 " ~ ~ 
main\ffff 


NULL Procedure Descriptor 
Flags: 

KIND: 

Signature Offset 

Entry Address: main\FFFF 

Procedure Descriptor (0000000000010000) • 

Fiags: 30 89 

pn ND: n PDSC$K KIND FP STACK 

FP is Base Register — ~ 

Rsa Offset: 0008 

Signature Offset 0000 

Entry Address: majn 

Ireg Mask: 20000004 <R2,FP> 


(09) 


(09) 


J - ZUUUU 

RA Saved @ 000000007F907AD8 
R2 Saved @ 000000007F907AE0 
FP Saved @ 000000007F907AE8 
Freg Mask: 00000000 

Slze: 00000020 


FFFFFFFF8255A1F8 

000000007FFBF880 

000000007F907B30 


invocation block 1 


FP: 000000007F907B30 

Procedure Descriptor (FFFFFFFF8255D910): 


Flags: 

KIND: 

Handler Valid 
FP is Base Register 
Rsa Offset: 

Signature Offset 
Entry Address: 

Ireg Mask: 


3099 

PDSC$K_KIND_FP_STACK (09) 


DBG> 


0048 
0001 

-2108317536 

RA Saved @ 000000007F907B78- 84 000000007FA28160 

“ l 000000007F907B80: 0000000000000000 

. f ed , @ o 0 . 00000007F907B88 : 000000007FF9C9EO 

^ @ nn 0 i 00 ° 0007F907B90: 000000007FA00900 

Freg uZt @ 000000 ^907B98: 000000007F907BB0 
rreg MasJc. 00000000 

Blz ®:' . 00000070 

Condition Handler: -2108303104 


prologue before the change in thelanre pllr <m Sidt ££ 
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SHOW STACK 


epilogue after restoration of the FP each look like a null frame, 
reported accordingly. ♦ 


and are 
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SHOW STEP 


Format 


Description 


Identifies the default qualifiers (/INTO /INSTRTTPTTr>M /mhott Tm 
currently in efFect for the STEP command. UCTI0N ’ NOSILENT and so on) 

SHOW STEP 


Example 


STEPr P ^ the *** 

j xl ,5 blliP com mand. If you did not enter a <WT 
man , the default qualifiers are /LINE, /OVER, /NOSILENT, and /SOURCE 

the ™ ^E p NOSOURCE' 
source display in output and 'do HicLJ^^ command (to eliminate redundant 
/LINE, /OVER, /NOSILENT, and /NOSOURCE CaS6 ’^ defaUlt qualifiers are 
Related commands: 

STEP 
SET STEP 


DBG> S/g™' N ° SYSTEM ' N0SHARE ' INSTRUCTION, NOSOURCE 

into routine calls, 


DBG> SHOW STEP 

step type, nosystem, noshare, nosource, nosilent i 
by instruction 

DBG> 


* SH0W STEP — d “■-*« 


Steps into called routines, but not those in system 
images 

Steps by instruction 

Does not display lines of source code while stepping 


the debugger take the 
space or in shareable 


CD-283 




SHOW SYMBOL 


SHOW SYMBOL 


Displays information about the symbols in the debugger's run-time symbol table 
(RST) for the current image. 


Note 


The current image is either the main ima § c '^“^B^mmand. 
established as the current image by a previous SET IMAGE comma 


Format 


SHOW SYMBOL symbol-name[, .. ] [IN scope[, • ■ • 11 


Parameters 


Qualifiers 


Alpha 


symbol-name fi , A valid symbol name is a single identifier or 

Specifies a symbol to be identi . „ ls an inte ger. Compound names 

a label na “ a °“ h ' S^VRRAYli^are not valid. If you specify the asterisk 

^fjdc "d ZraSTtstTn symbols are listed. You can use the wildcard 

within a symbol name. 

Specifies the name of a module, routine - «-*•** 

'Z scopes must be in set modules 

in the current image. 

The SHOW SYMBOL the 6 

current image that both match e specl omit this parameter, all set 


S3TL addtoss 

specification is the method °*'^ indirection or an offset 

be the symbol’s memory address, but it can ifications too complicated 

"complex address specifications." 
routine, entry point, or Ada package. ♦ 

Ehsplays^ymbols you have defined with the DEFINE command (symbol 
definitions that are in the DEFINE symbol table). 
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SHOW SYMBOL 


/DIRECT 

/LOCAL 

Displays symbols that are defined with the DFF’TN'Ti'/T or 1 at j 

definitions that are in the DEFI^ZZ tabled (symbo1 

/TYPE 

Displays data type information for each selected symbol. 

/USE_CLAUSE 

Si 

L ^Sfled 0 sS“;\ a ” y se*L SUWam ' “ d “ « «“* 


Description 


SS *""‘“—I - - SS~,tSK 

oil ^ image (that is, in all set modules and in the GST for that imao- ^ 

HHHsiP# 

deto^/tMhe^DEFINE ^ ’““S" information aho ^ symbols 

proiamTThe^otW rn ^ the Symb ° ls that are drived from your 

youfprogram. quallfiers dls P^y information about symbols defined within 

For information specific to Ada programs, see the Language ADA help topic. 
Related commands: 

DEFINE 

DELETE 

SET MODE [NOJLINE 
SET MODE [NOISYMBOLIC 
SHOW DEFINE 
SYMBOLIZE 


Examples 


1. DBG> SHOW SYMBOL I 
data F0RARRAY\I 
DBG> 


deflned * forar ~ „. 
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SHOW SYMBOL 


2 DBG> SHOW SYMBOL/ADDRESS INTARRAYl 
data F0RARRAY\INTARRAYl 

descriptor address: 0009DE8B 

DBG> 

This command shows that symbol! NTARRAY1 is Mined in module 
FORARRAY and has a memory address of 0009DL8B. 

3. dbg> show symbol *pl* 

This command lists all the symbols whose names contain the string "PL". 

4. DBG> SHOW SYMBOL/TYPE COLOR 

data SCALARS\MAIN\COLOR ...... 4 hvtps 

enumeration type (primary, 3 elements), site. 4 by 

This command shows that the variable COLOR is an enumeration type. 

5. DBG> SHOW SYMBOL /TYPE/ADDRESS * 

This command displays all information about all symbols. 

6. DBG> SHOW SYMBOL * IN MOD3\COUNTER 

routine M0D3XC0UNTER 
data MOD3\COUNTER\X 
data M0D3\C0UNTER\Y 

DBG> 

This command lists all the symbols that are defined in the scope denote y 
the path name MOD3\COUNTER. 

7. DBG> DEFINE/COMMAND SB=SET BREAK 
DBG> SHOW SYMBOL/DEFINED SB 
defined SB 

bound to: SET BREAK 
was defined /command 

DBG> , 1 

. . i nFFTNE/COMMAND command defines SB as a symbol 

K: SYMBOL/DEFINED command 

displays that definition. 
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SHOW TASK 


Format 


w- (also caned a 


SHOW TASK [task-spec[, ... ]] 


Parameters 


%ACTTVE_TASK 
%CALLER_TASK 

%NEXT_TASK 

%PREVIOUS_TASK 

%VISIBLE_TASK 


Qualifiers 


task-spec 

Specifies a task value. Use any of the following forms: 

' fha^rr^: 8 aexprc8si °" 

• A task ID (for example, %TASK 2), as indicated in a SHOW TASK display. 
One of the following task built-in symbols: 

The task that runs when a GO, STEP, CALL, or 
EXIT command executes. 

(Applies only to Ada programs.) When an accept 
statement executes, the task that called the entrv 
associated with the accept statement. 

The task after the visible task in the debugger’s 
task list. The ordering of tasks is arbitrary but 
consistent within a single run of a program. 

The task previous to the visible task in the 
debugger’s task list. 

The task whose call stack and register set are the 
cuirent context for looking up symbols, register 
values, routine calls, breakpoints, and so on 

5 


/ALL 

/CALLS[=n] 

/FULL 

Displays additional information for each task selected for display. The 
or ^TATKTICr atl ° n “ * y ° U USe /PULL * itself «* with /CALLS 

/HOLD 

/NOHOLD (default) 

Selects either tasks that are on hold, or tasks that are not on hold for display. 
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SHOW TASK 


* 73 % 


Tf vou do not specify a task, /HOLD selects all tasks that are on hold. If you 
specify a task list, /HOLD selects the tasks in the task list that are on o . 

_ .n /mot-TOT D qplects all tasks that are not on hold. If 

you°specify°a task list, /NOHOLD selects the tasks in the task list that are not on 

hold. 

tasks in the task list that have any of the priorities specified. 

OTSPEOTED kS o?TESm A raD° f V a 

S task .is, tiat are in any of the states spewed. 

of total schedulings (also known as context switches), the more tasking ove 
there is. 

/TIME_SLICE 

Displays the current time-shoe 
"y entered, displays the time-shoe 

program. If no time-slice value was previously established, the value 
is, time slicing is disabled. ♦ 


Description 


A task can test appear in ~ 

I“tSninated. By default the SHOW 
TASK command displays one line of information for each task selected. 

Related commands: 

DEPOSIT/TASK 

EXAMINE/TASK 

(SET,SHOW) EVENT_FACILITY 

SET TASK 


Examples 


! dbg> show event^facility 
event facility is ADA 


dbg> show 

TASK/ALL 


task id 

pri hold 

state 

* %TASK 1 

7 

RUN 

%TASK 2 

7 HOLD 

SUSP 

ITASK 3 

6 

READY 


substate 

Accept 


task object 
122624 
H4.MONITOR 
H4.CHECK_IN 


DBG> 


UDU/ 

In this example, the SHOW EVENTFACILITY command identifies ADA as 
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SHOW TASK 


tsfsspsss 

is in the RTO statei P ’ “ 18 3180 0,6 active tosk <«* *«* that 

2. DBG> SHOW TASK %ACTIVE_TASK,%TASK 3,MONITOR 

Splay mmand SdeCtS the 3CtiVe t3Sk ’ %TASK 3 ’ and task MONITOR for 

3. DBG> SHOW TASK/PRI0RITY=6 

This command selects all tasks with priority 6 for display. 

4. DBG> SHOW TASK/STATE= (RUN,SUSP) 

SeleCtS a11 tasks that are either running or suspended for 

5. DBG> SHOW TASK/STATE=SUSP/NOHOLD 

d%lay. mmand SdeCtS aU taSkS that are b ° th sus P en( ied and not on hold for 


6 . 


dbg> show task/state= (RUN,SUSP)/PRI0=7 %VISIBLE_TASK,%TASK 3 

Selects f0r dispIay those tasks am ong the visible task and 
priority 7. ^ m Glther ^ RUNNING or SUSPENDED STATE and have 


CD-289 




SHOW TERMINAL 


SHOW TERMINAL 

Identifies the current terminal screen height (page) and width being used to 


format output. 


Note 


is command is not available in the DECwindows Motif interface to the 


This 
debugger. 


Format 


SHOW TERMINAL 


Description 


TERMINAL (usually 24 lines and 80 columns for VT-senes terminals). 

Related commands: 

SET TERMINAL 
SHOW DISPLAY 
SHOW WINDOW 


Example 


dbg> show terminal 

terminal width: 80 
page: 24 


This command displays the current terminal screen width and height (page) as 
80 columns and 24 lines. 
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SHOW TRACE 


Displays information about tracepoints. 


Format 


Qualifiers 


SHOW TRACE 


/PREDEFINED 

Displays information about predefined tracepoints. 

/USER 

Displays information about user-defined tracepoints. 


Description 


Alpha 


Examples 


curr 

counts, and so on, and whether the tracepoints are deactivate) * 

SS-S'St™ su 

B^«Ks2SsS=3S~ 

Related commands: 

(ACTIVATE,DEACTIVATE) TRACE 
(SET,CANCEL) TRACE 
CANCEL TRACE 


1. DBG> SHOW TRACE 

tracepoint at routine CALC\MULT 
tracepoint on calls: 

DBG> RET RSB BSBB JSB 


BSBW 


CALLG CALLS 


sSSSSSSSSSSTstS? 

one of the instructions RET, RSB, BSBB, JSB, BSBW, CALLG or " 


CD-291 





SHOW TRACE 


2 DBG 2> SHOW TRACE/PREDEFINED 

' pr t £ S? -* m hi soo,,ce 

SET SSSSKSj - « O » 

(EXAM/INSTRUCTION .0\%PC)) 
predefined tracepoint on program termination 
DBG_2> 

This command identifies the predefined tracepoints that are <onrt»l 
The example shows the predefined tracepoints that 5?mCESS ha“ 
bv the debugger tor a multiprocess program (when DBG$ p ROCEbb nas 
Se value MULTIPROCESS). The tracepoint on prognam activati,>n tagge 

ssssias? 

is triggered. The tracepoint on program termination triggers 
process does an image exit. 
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SHOW TYPE 


SHOW TYPE 



not have a compiler- 
- override type. 


Format 


SHOW TYPE 


Qualifiers 


/OVERRIDE 

Identifies the current override type. 


Description 



: hav e a compiler-generated 
command. If you did not enter 


is the override type last 
l. If you did not enter a SET 


TYPE/OVERRIDE command, the override type is » 


is "none". 


Related commands: 


CANCEL TYPE/OVERRIDE 

DEPOSIT 

EXAMINE 

(SET,SHOW,CANCEL) MODE 
(SET,SHOW,CANCEL) RADIX 
SET TYPE 


Examples 


1. DBG> SET TYPE QUADWORD 
DBG> SHOW TYPE 
type: quadword integer 
DBG> 

In this example, yoi 
a compiler-generate 
default type for thoi 
debugger interprets 
integers unless you 
EXAMINE commanu,. 

2. DBG> SHOW TYPE/OVERRIDE 
type/override: none 
DBG> 



This command indicates that no override type has been defined. 
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SHOW VECTORJ/IODE (VAX Only) 


SHOW VECTOR_MODE (VAX Only) 


On VAX processors, identifies the current vector mode (synchronized or 
nonsynchr onized). 

Applies to VAX vectorized programs. 


Format 

SHOW VECTOR_MODE 


Description 


The current vector mode is the mode established with the SET VECTOR MODE 
command. If you did not enter a SET VECTOR.MODE command, the default 
vprtnr mode is NONSYNCHRONIZED. 


Related commands: 

SET VECTOR_MODE [NOISYNCHRONIZED (VAX only) 
SYNCHRONIZE VECTOR_MODE (VAX only) 


Example 

dbg> show vector_mode 

Vector mode is nonsynchronized 

dbg> set vector_mode synchronized 
dbg> show vector_mode 

Vector mode is synchronized 
dbg> 

The SHOW VECTOR_MODE command indicates the effect of the SET VECTOR. 
MODE command. ♦ 
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SHOW WATCH 


SHOW WATCH 


Format 


Displays information about watchpoints. 


SHOW WATCH 


Description 


Example 


or°Do'c?auBM* J //JTER are 

counts, and so on, and whether the watchpoints are deactivated 

s2&’5zr=v!t £! s±3&?- 

action.) ° fn 18 Z6r0 ’ at Which time the ^bugger takes watch 

Related commands: 

(ACTIVATE,DEACTIVATE) WATCH 
(SET,CANCEL) WATCH 


DBG> SHOW WATCH 
watchpoint of MAIN\X 
watchpoint of SUB2\TABLE+20 
DBG> 

puS, d A: <■ H 

the address denoted by the address expressL TABLeT ^ beyond 
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SHOW WINDOW 



SHOW WINDOW 

Identifies the name and screen position of predefined and user-defined 


screen-mode windows. 

___ Note- 

This command is not available in the DECwindows Motif interface to the 
debugger. 


Format 


SHOW WINDOW [window-name[, ... ]] 


Parameters 


“re listed. You can use the wildcard within a window name. Do not specify 
window definition name with the /ALL qualifier. 


Qualifiers 

/ALL 

Lists all window definitions. 

Description 

Related commands: 

(SHOW,CANCEL) DISPLAY 
(SET,SHOW) TERMINAL 
(SET,CANCEL) WINDOW 
SHOW SELECT 


Example 

dbg> show window lh*,rh* 

window LH1 at (1,11,1,40) 
window LH12 at (1,23,1,40) 
window LH2 at (13,11,1,40) 
window RH1 at (1,11,42,39) 
window RH12 at (1,23,42,39) 
window RH2 at (13,11,42,39) 

DBG> 

This command displays the name and screen position of all screen win ow 
definitions whose names start with LH or KM. 
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SPAWN 


£s«^ a b xss 


Note 


d ? b ~ d iS Mt available in the DEC ™<*ows Motif interface to the 


Format 


Parameters 


SPAWN [DCL-command] 


Qualifiers 


DCL-command 

“ -:as,“ =i=" * 

ei U Da n :Sds a K,he”rr d ’ 8 t SUb f P r eSS iS ~“ a " d *» can then 

to the parent process iwith the DCL commid " a f taChin!! 

debugging session. command A11ACH) returns you to your 

SS/e T, Sm"’ f° U encl ° Se “"™“ d <■> 


/INPUT=file-spec 

«. ±1 you specuy a UCL command strine with thp CJPAWTS.T __ j , 

not use the asterisk («) wildcard character to the S l P s r S S c r t to n nnmated ' ““ 

/OUTPUT=file-spec 

/WAIT (default) 

/NOWAIT 

ftTsubpr^f p r ss) is suspended whue 

session until the subpr^ess is ^nated Yn SUSpends the bugging 

until control returns to the parent process'. U debug ^ er commands 
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The /NOWAIT qualifier executes the subprocess mnnSg 1 ^ 

session. You can enter debugger comman ® ^ 1 d P ith the SPAWN 

indicates when the spawned subprocess completes. 

run after the debugger version number has appeared in the oom 
View. 

Optionally, you can execute the Kept Debugger in the following manner: 

$ DEFINE DBG$INPUT NL: 

$ SPAWN/NOWAIT RUN DEBUG/KEEP 


Description 


Examples 


session or losing your current debugging context. 

t addition vou can spawn a DCL command SPAWN. DCL processes the second 
SPAWN command, including any qualifier specified with that comman . 

Related command: ATTACH. 


1. DBG> SPAWN 
$ 

i u iv,at tVip SPAWN command, without a parameter, creates 

enter i»CL commands. U g ont to 

return to the debugger prompt. 

2 DBG> SPAWN/NOWAIT/INPUT=READ_NOTES/OUTPUT=0428NOTES 

This command creates a subprocess that U; exerted 

SggSSSSS^Stratton /written to 
the file 0428 NOTES.LOG. 

3 DBG> SPAWN/NOWAIT SPAWN/OUT=MYCOM.LOG 0MYCOM 

This command creates a subprocess that is ^^"^'tT^eSL the 

operation is 

written to the file MYCOM.LOG. 
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Format 


Executes the program up to the next hue, instruction, or other specified location. 


STEP [integer] 


Parameters 




integer 

°f 1 ** U " itS <lines > Actions, and 
unit exe '" te <‘- If you omit the parameter, the debugger executes one step 


Qualifiers 


/BRANCH 

Execute^ the program to the next branch instruction STEP/BRA NPH ,, 

same effect as SET BREAK/rEMPORARY/BRANCIRGO 

/CALL 

Executes the program to the next call or return instruction STFP/pat t u .u 
same effect as SET BREAK/TEMPORARY/CALL;GO STEP/CALL has the 

/EXCEPTION 

,, ecutes the program to the next exception, if any. STEP/EXC EPTTON i,„„ 

the same effect as SET BREAK^EMPORARY/EXCEPTION-rn If 

occurs, STEP/EXCEPTION has the same effect at G O ’ exception 

/INSTRUCTION 

OTEMNSraUCTMN h«? t b° PC0<ie ' the Pr0gram to the instruction 

/INSTRUCTION™ ^ ^ “ SET BKEAK/TEMTORARY 

/INSTRUCTION=(opcode[, ... ]) 

On VAX processors, if you specify one or more opcodes executes 

list ^TEBTNSTRUCTfoNf^^^r Wh ° Se ° PC ° de iS specified in th e 
SET BREAK^MPORARY^SreubhoLtp^ 81 ” 6 j)®o ““ 

» w. ", 

/INTO 

execution is currently suspended at a routine call STFP/TlSJTO ^ , , 

is the opposite of/OVER (the defaulfbfha^ “ “ ^ qUa ‘ ifier 

SoS^oSysC qualifiers^ 
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40 ^ 


Alpha 


/JSB 

/NOJSB 

On VAX processors, qualifies a previous SET STEP INTO command or a current 
STEP/INTO command. 

If execution is currently suspended at a routine call and the 

by a JSB instruction, STEP/INTO/NOJSB has sa a ^^ TEP/0VER - 

Otherwise STEP/INTO/NOJSB has the same effect as STEP/INIO. 

Use STEP/INTO/JSB to override a previous SET STEP NOJSB »mmmriSTHP 
/INTO/JSB enables STEP/INTO to step into routmes called by a JSB mstructio , 
as well as into routines called by a CALL instruction. 

The /JSB qualifier-is 

“n MOL run-time library routines are called 

by the JSB instruction. ♦ 

/LINE 

Executes the program to thenextlinetf source "teS wbe"ed 

cikios over any source lines that do not resu RTCFAK 

sKips uvci cx j crrT?r)/T TTsJF ha* the same effect as oHil 

Savior for al, languages. 

SSSSESaSSSSSST 

/INTO. 

SSSa. routine in which 

instruction (that is, up to the pom j P loca j environment (for example, 

calling routine). This enablies you tdeletes the 

roS^cJlt^ from theTall stack. STEP/RETURN has the same effect as 

SET BREAK/TEMPORARY/RETURN;G0. 

STEP/RETURN n executes the program up n levels of the call stack. 

/SEMANTIC_EVENT 

On Alpha systems, executes the program to the next semantic event. 
STEP/SEMANTIC_EVENT simplifies debugging optimized code. (See Description 
below.) ♦ 

/SHARE (default) 

Quahfies^a previous SET STEP INTO command or a current STEP/INTO 
command. _ 

If execution is currently suspended at a ^ ^ater^ro^^ 

/INTO/NOSHARE has the same effect as STEP/OVEK. utnerwise, 

/NOSHARE has the same effect as STEP/INTO. 
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Description 


Use STEP/INTO/SHARE to override a previous SFT STF p mhcuadd 
STEP/INTO/SHARE enables STEPANTO Z T T u NOSHARE command, 
as well as into other “nt of Staf ^ mt ° ShareaMe ima ® e 

/SILENT 

/NOSILENT (default) 

Zf? t h ; STO^ha^compl^te^^he^OSILENT 

that 1 ^: ris ^ e rss^r ifies 

overrides /SOURCE. p y a ' ine /blJ -ENT qualifier 

/SOURCE (default) 

/NOSOURCE 

sS°has W ^ r eted ^SOURCE'” 6 'ST* '"f^ 

is displayed. ^ T*- ' ine 

displayed. The /SILENT qualified overrides /SOURCE^ J oVm aot 

[NOJSOURCE command. /SOURCE. See also the SET STEP 

/SYSTEM (default) 

/NOSYSTEM 

»mmand a Pre ™" S ^ ^ INT ° C ° mmand or a STEP/INTO 

ST?STO^OS?I™Kr t n ,, ded a ‘ a Ca “ 40 a SyStem «" PI space). 

/INTO/NOSYSTFM hn« 6 S ^ ne e ^ ect as STEP/OVER. Otherwise, STEP 

in i u/in uoiol EM has the same effect as STEP/INTO. 

Use STEP/INTO/SYSTEM to override a previous SET STEP NOSYSTEM 
command. STEP/INTO/SYSTEM enables STEP/TNTO Z lt ^USYSTEM 
routines, as well as into other kinds of routes 40 ^ m *° SyStem 

/VECTORJNSTRUCTION 

^^CTORTh^TItUCTION^as 1 ^ 1 ^ 0 ^ 3111 1° ** ^ Vector inst ™*<>n. STEP 

/VECTOR~INSTRUCTION;GCL ♦ ^ “ SET BREA *™MPORARY 


^ciffe^ou^pro^mi (the^thws areC^^LfEMT^ar^TGO).^ 3 * “ * - * 

The behavior of the STEP command depends on the following factors: 

The default STEP mode previously established with a SET STEP command, if 

The qualifier specified with the STEP command, if any 

The number of step units specified as the parameter to the STEP command, if 


Executes a line of source code (the default is STEP/LINE). 
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Alpha 


2 Reports that exeeution has completed by issuing a "Stepped to " message 
(the default is STEP/NOSILENT). 

3. Displays the line of source code at which execution is suspended (the default 
is STEP/SOURCE). 

4. Issues the prompt. 

The following qualifiers affect the location to which you step: 

/BRANCH 

/CALL 

/EXCEPTION 

/INSTRUCTION 

/INSTRUCTION=(opcode[, . . . ]) (VAX only) 

/LINE 

/return 

/SEMANTIC_EVENT (Alpha only) 

/VECTORJNSTRUCTION (VAX only) 

The following qualifiers affect what output is seen upon completion of a step: 

/[NOISILENT 

/[NO]SOURCE 

The following qualifiers affect what happens at a routine call: 

/INTO 

/[N01JSB (VAX only) 

/OVER 

/[NOISHARE 

/[NO]SYSTEM 

If you plan to enter several STEP commands with the sa “ e X^alTfiers°(for 
oJL fw use the SET STEP command to establish new default qualifiers l 
can first lue the_SE N0SYSTE M makes the STEP command behave like 

STOP/INTO/NOSYSTEM) . Then you do not have to use those qualifiers wi e 
STEP command. You can override the current default qualifiers for teu 
of a singS STEP command by specifying other qualifiers. Use the SHOW STEP 
command to identify the current STEP defaults. 

Tf an exception breakpoint is triggered (resulting from a SET BREAK 
/FXPEPTION or a STEP/EXCEPTION command), execution is suspended 

On Alpha systems, if your program has been compiled with toeKjPTj^ 

When you are ' 

stsssisSHSis:. 

effect (semantic event) occurs. 

A semantic event is one of the following. 

• Data event — An assignment to a user variable 

. Control event - A control flow decision, with a conditional or unconditional 
transfer of control, other than a call 
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Call event - A call (to a routine that is not stepped over) or a return from a 

SSZIlr-' ° f COn “' * Ca “ ‘ S * —»* «* ™e major 

When two instructions are required to assign to a complex or X floating 
value, only the first instruction is treated as a semanS event '® 

• When there are multiple branches that are part of a single higher-level 

—: S ^ SfS £“ a case or sel “* 

s^h n as a a C Mlfto m OTS*°MOra‘ in h^■‘K “ J“, helper routine, 

To step into such a routine, you must either: 

Set a breakpoint at the routine entry point or 

' S£S SSS5S,>.-iS 

' sssjste“ ssirsas: 

^ h e e n^If P/SEM f ANTIC ~ EVENT command caus es a breakpoint to be set at 
For more information on debugging optimized programs, see Chapter 13. . 

freTamlin^S 

note the following additional point! ** ^ MUL TIPROCESS), 

The STEP command is executed in the context of the visible process hut 
images in any other processes that are not on hold (through a^SET PROCESS 

® breadr,7s?Eprmm aU d 0 r d to eXCCUte ' Ify °“ “«» DOcoZS 

command to one or more processes thp j 

“ eMed h> the context of each specified proSTS^’is not In houTut 

process *22 execution continues until it is suspended in any 
* , lhat pomt > execution is interrupted in any other processes that 
xecu mg images, and the debugger prompts for input. 
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On VAX systems the STEP/OVER command results in stepping into, not over, 
FOTtran Run-Time Library routines. For more information, (see Chapter 13). ). . 

Related commands: 

CALL 

DO 

EXIT 

GO 

SET BREAK/EXCEPTION 

SET MODE [NOIINTERRUPT 

SET PROCESS 
(SET,SHOW) STEP 

Examples 

1. DBG> SHOW STEP 

step type: source, nosilent, by line, 
over routine calls 

dbg> STEP 

stepped to SQUARES$MAIN\%LIWE^^^^^ DATAFILE.DAT' , STATUS=' OLD') 

DBG> 

_ ... a fV,o QWOW STEP command identifies the default qualifiers 

™tlX:L fcr SS —d. In this case, the STEP command, 
SutUy pa^nSers or qualifiers, executes the next line 

After the STEP command has completed, execution is suspended at the 

beginning of line 4. 

2 . DBG> STEP 5 

stepped to MAIN\%LINE 47 

47: SWAP(X, Y) ; 

DBG> ™ 

This command executes the next 5 lines of source <iode.^ After fte STEP ^ 
command has completed, execution is suspended at the begin g 

3 . DBG> STEP /INTO 
stepped to routine SWAP 

23: procedure SWAP (A,B: in out integer) 

dbg> STEP 

stepped to MAIN\SWAP\%LINE 24 

24- TEMP: integer := 0; 

sfeppeHTSn fro. 21 to «AI„\S»AMU»E 29 

29: end SWAP; 

DBG> 

SSIZt“ , up to the point just prior to transferring control back to 
the calling routine). 
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DBG> SET STEP INSTRUCTION 
DBG> SHOW STEP 

step type: source, nosilent, by instruction, 
over routine calls 

DBG> STEP 

stepped to SUB1ULINE 26: MOVL S A #4,B A -20(FP) 

26: Z:integer:=4; ' ' 

DBG> 

S=3£553S33ESS~ 

is ^P-ded 
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SYMBOLIZE 

Converts a memory address to a symbolic representation, if possible. 


Format 

SYMBOLIZE address-expression[, ... ] 


Parameters 


address-expression 

Specifies an address expression 
wildcard character. 


to be symbolized. 


Do not use the asterisk (*) 


Description 


Alpha 


If the address is a IVSssTnd a ifne 

4 address, the toe number is included in the 

symbolization. 

If the address is a register address, the debugger jTbol 

r<£“^e"nam!^SfiW, ^example, is also displayed. 

address. A symbol whose address specification is too complex is ign 

routine, entrypoint, or Ada package specified by these addresses. 

If the debugger can tad no symbolization for the address, a message is displayed. 


Related commands: 

EVALUATE/ADDRESS 
SET MODE [NO]LINE 
SET MODE [NOISYMBOLIC 
(SET,SHOW,CANCEL) MODULE 
SHOW SYMBOL 


Examples 


1. DBG> SYMBOLIZE %R5 
address PR0G\%R5: 

PR0G\X 

DBG> , , . 

This example shows that the local variable X in routine PKOG is located m 

register R5. 
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DBG> SYMBOLIZE %HEX 27C9E3 
address 0027C9E3: 

M0D5\X 

DBG> 


This command directs the debugger to treat the integer literal 27C9ES - 
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SYNCHRONIZE VECTOR_MODE (VAX Only) 

On VAX processors, forces immediate synchronization between the scalar and 
vector processors. 

Applies to VAX vectorized programs. 


Format 


Description 


SYNCHRONIZE VECTOR_MODE 

The SYNCHRONIZE VECTOR_MODE command forces immediate 
synchronization between the scalar and «*tor processors by rssrnng SYNC 
and MSYNC instructions. The effect is as follows. 

* r- „ i-Unt was caused bv a vector instruction and was still pending 

exception handler (if one is available at that location in the program). 

* 

instruction that was still being executed completes execution. 

„ . . .a- GYNCHRONIZE VECTOR MODE command is equivalent to issuing 

Entering the biJN^nKuiNi/i^ r, V ncrram at which execution 

SYNC and MSYNC instructions at the location in the progra 
is suspended. 

By default, the debugger does not force synduoniz^onhrt^™*e^ar 
and vector processors during program execution (SET VEC ™^^ CT0R 
NOSYNCHRONIZED). To force such synchronization, use the S 
MODE SYNCHRONIZED command. 

Related commands: 

SET VECTOR_MODE [NO]SYNCHRONIZED (VAX only) 

SHOW VECTOR.MODE (VAX only) 


Examples 

i. 


SYNCHRONIZE VECT0R_M0DE 

UG-I-SYNCREPCOM, Synchronize reporting complete 

, command forces immediate synchronization between the scalar and 
or processors. In this example, the diagnostic message in ica e 
synchronization operation has completed and that all pending vec 
iptions have been delivered and reported. 
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DBG> STEP O 

stepped to .MAIN.\SUB\%LINE 99 

99: WDIVD V1,V0,V2 

DBG> STEP 0 ' ' ^ 

stepped to .MAIN.\SUB\%LINE 100 
100: CLRL R0 

DBG> EXAMINE/FLOAT %V2 0 

0\%V2 

£0]: 13.53400 

[2]: 247 S 2450 ° Perand ' enC ° ded aS floatin 9 divide by zero 

DBG> SYNCHRONIZE VECTOR MODE O 

■s SYSTEM-F- VARI TH, vec t°r arithmetic fault, summary=00000002 

break on unhandled^xLSJ 004 ' P ^ =000002E1 ' PSL=03C00010 ' 

100: CLRL JoT PreCedlng •™.\SUB\%LINE 100 

DBG> 

n.e comment, that follow refer to the callout, in the previous example: 

SZSnTeSuW '"Zume' T T" “th™ jUSt bef ° re 

instruction will t rig6 er a 

® 2"? f TEP comman d executes the WDIVD instruction u 

thatute exception is not delivered at this point 

in element 1 o^e°tJtiZtan mma8e 

point divide-by-zero exception waTtS ^X^r" 8 ' 

Shve™ c ° mmand forces the immediate 


0 
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TYPE 


Displays lines of source code. 


Format 


TYPE f[module-name\]line-number[:line-number] 

[,[module-name\]line-number[:line-number][, 


• •]]] 


Parameters 


module-name , displayed. If you specify 

enter a ST SC«B.—*— for 

SS associated with the hrst named scope. 

“TUiler-generated line number (a number used to label a source 
language statement or statements). 

If you specify a single line number, the debugger displays the source code 
corresponding to that line number. 

7 

corresponding to that range of line numbers. 

largest line number in the module. 

After displaying a singleUne numbeHtbatis, by entering 
module by entering a TYPE comnm can then display the next line and 

successive tZ "tog *is seguence, in effect, reading through your source 

program one line at a time. 


Description 


The TYPE command displays the lines of source^code ident if y lines of 

" in a 

listing and in a screen-mode source display. 

• 4 -v, TVPF rommand, the module must be set. 
S;Sw TuTn^nmne whether a particular module is 

set. Then use the SET MODULE command, if necessary. 
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Examples 


t is di r, ed a i the c ™‘ ~» 

specified and a„ y sJLdin^iS^ “* 

Related commands: 

EXAMINE/SOURCE 

tvl 2^i K ’ TRACE ’ WATCH) / [ NO]SOURCE 
SET MODE [NOJSCREEN 

(SET,SHOW,CANCEL) SCOPE 

SET STEP [NOJSOURCE 

STEP/[N OJSOURCE 


L/Cb^ 160 

module COBOLTEST 

160: START-IT-PARA. 

DBG> TYPE 
module COBOLTEST 

161; MOVE SCI TO ESO 

DBG> 




2. DBG> TYPE 160:163 
module COBOLTEST 


160 
161 
162 
163 
DBG> 


START-IT-PARA. 

MOVE SCI TO ESO. 
DISPLAY ESO. 

MOVE SCI TO ESI. 


moIT mand di8PlayS “ neS 160 to 163 - usin S current scope to locate the 


DBG> TYPE SCREEN_IO\7,22:24 

This command displays line 7 and lines 22 to 24 in module SCREENJO. 
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WHILE 

Executes a sequence of commands while the language expression (Boolean 
expression) you have specified evaluates as true. 

Format 

WHILE Boolean-expression DO (command[; • • • ]) 


Parameters 


Boolean-expression 

Specifies a language expression 
in the currently set language. 


that evaluates as a Boolean value (true or false) 


command , Tf V mi sDecifv more than one command, separate 

r—SS r —s (0 y At each **“ 

syntax of any expressions in the commands and then evaluates them. 


Description 


The WHILE command evaluatesaBool^ 

SLtjSS’ sS^valuating the ^olemt expression and executing the 
command list until the expression is evaluated as fals . 

If the Boolean expression is false, the WHILE command terminates. 

Related commands: 

EXITLOOP 

FOR 

REPEAT 


Example 


DBG> WHILE (X .EQ. 0) DO (STEP/SILENT) 

This command directs the debugger to keep stepping through the program untd 
X no longer equals 0 (FORTRAN example). 
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_A 

Predefined Key Functions 

o™«ti*: 0 “ u srL^ t pre ) deflned functions (comma " ds ' 

keypad, to theShSrfS^mST t ^ aSSlgned t0 keys on the numeri ' 
certain commands with fewer keystrokes than theSG keyS y ° U Can enter 
keyboard. For example pr'LiSe C^ at the 
to typing GO and then Dressing tha t? 0 + 1 ’ , 0n the key P ad 1S equivalent 

have an LK201 keyboard have additional™ ^ erndna ^ s and workstations that 
on VT100 keyboards (for example “HeW’ or^Re^^ 7* C ° mp f ed to those 
are also assigned debugger functions^ " Remove >’ *these keys 

To use function keys, keypad mode must be enabled (SET MODE KFYPAm 

command^ ““ diSaWe m0de by “*“*5 SET^MOMNOKEWAD 

identified in summa^form^ debugger are 

ssr rather thmdebuggw — 

A.1 DEFAULT, GOLD, BLUE Functions 

A given key typically has three predefined functions: 

DEFAULT 'functfon ered ^ PreSSing the ^ key by itself ‘ This ia the 

* r r ea t g the PF1 key and then 

the GOLD key LD funCtl0n ’ because PF 1 is also called 

■ iEmSS 1 ? rel t eas t the PF4 key and then 

the BLUE key. UE functl0n > because PF4 is also called 
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Figure A-1 Keypad Key Functions Predefined b, the Debugger-Command Interface 


<F17 

> 

F18 f 

=19 ' 

=20 ^ 

DEFAULT 

(SCROLL) 


MOVE 

EXPAND 
(EXPAND +) 

CONTRACT 
(EXPAND -) 


> 



_/ 

r pfi 


PF2 

PF3 

PF4 ^ 

GOLD 

GOLD 

GOLD 


HELP DEFAULT 
HELP GOLD 

HELP BLUE 

SET MODE SCREEN 
SET MODE NOSCR 
DISP/GENERATE 

BLUE 

BLUE 

BLUE 

7 


r* \ 

9 


DISP SRC,INST,OUT 
DISP INST,REG,OUT 
DISP 2 SRC, 2 INST 

SCROLL/UP 

SCROLLTOP 

SCROLL/UP... 

DISPLAY next 

SET PROC next 
DISP 2 SRC 

DISP next at FS 

DISP SRC, OUT 



c J 

"__ 

_ 


> 

5 


J 

SCROLL/LEFT 

SCROLULEFT:255 

SCROLULEFT... 

EX/SOU .0\%PC 
SHOW CALLS 
SHOW CALLS 3 

SCROLL/RIGHT 
SCROLL/RIGHT :255 
SCROLL/RIGHT... 

GO 

SEL/SOURCE next 
SEL/INST next 

L 



_> 


1 


-' 

3 

ENTER 

EXAMINE 

EXAM A (prev) 

DISP 3 SRC, 3 INS! 

SCROLL/DOWN 
SCROLLVBOTT OM 
‘ SCROLUDOWN... 

SEL SCROLL next 
SEL OUTPUT next 
DISP 3 SRC 




_> 

* 

ENTER 

0 

STEP 

STEP/INTO 

STEP/OVER 

RESET 

RESET 

RESET 


V_ 




J 


"MOVE" 


MOVE/UP 
MOVE/UP:999 
MOVE/UP :5 


MOVE/LEFT 
MOVE/LEFT :999 
MOVE/LEFT'.IO 


MOVE/RIGHT 
MOVE/RIGHT :999 
MOVE/RIGHT:10 


MOVE/DOWN 
MOVE/DOWN :999 
MOVE/DOWN :5 


"EXPAND" 


EXPAND/LEFT 
EXPAND/LEFT :999 
EXPAND/LEFT:10 


EXPAND/UP 
EXPAN D/UP.999 
EXPAN D/UP:5 


EXPAND/RIGHT 

EXPAND/RIGHT:999 

EXPAND/RIGHTiIO 


EXPAND/DOWN 
EXPAN D/DOWN :999 
EXPAND/DOWN :5 


LK201 Keyboard: 

Press 
FI 7 
F18 
F19 
F20 

VT-100 Keyboard: 

Type 

SET KEY/STATE=DEFAULT 
SET KEY/STATE=MOVE 
SET KEY/STATE=EXPAND 
SET KEY/STATE=CONTRACT 


Keys 2,4,6,8 

SCROLL 

MOVE 

EXPAND 

CONTRACT 


Keys 2,4,6,8 

SCROLL 

MOVE 

EXPAND 

CONTRACT 


"CONTRACT’ 

/f- 


EXPAND/UP-.-1 
EXPAN D/UP-999 
EXPAND/UP:-5 


EXPAND/LEFT:-1 

EXPAND/LEFT-999 

EXPAND/LEFT:-10 


EXPAND/RIGHT :-1 

EXPAND/RIGHT-999 

expand/right-.-io 


Jr 


■V 


EXPAND/DOWN:-1 
EXPAN D/DOWN :-999 
EXPAN D/DOWN :-5 


ZK-0956A-GE 


a i f u« nFFAULT GOLD and BLUE functions are listed within each 

cdon); piling « and then KPO 
enters the command STEP/OVER (BLUE function). 
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!SS exoeptT ae^UE 1 ? k T d * 7 ? "* termi " ated 

^ZT^TtZ^rtZ are symbolized wi ‘ h a ^g'eSsT f 

RETURN. For example 'to s'croR do™ “I'ine"f 17 “ Parameter the " P reaa 


1. 

2 . 

3. 

4. 


Press the PF4 key. 

Press keypad key KP2. 
TVpe :12 at the keyboard. 
Press the Return key. 


2 Key Definitions Specific to LK201 Keyboards 


and d ° nat ^ - 

for some keys, an equivalent kevnad l U the e< l uivalent command and, 

LK201 keyboard qU1Valent keypad key that y° a can use if you do not have an 



Keys that Scroll, Move, Expand, Contract Displays 

By default, keypad keys KP2, KP4 KP6 and kps ^ 

display. Each key controls a directionCdow/ lldtriSt ^ CUITent scrollin g 
By pressing keys F18 F19 or F20 J, ’ i !? gh , t ’ and up ’ respectively). 
EXPAND or CONTRAPT U + F2 f n plaCe the ke yPad in the MOVE, 

can uTkeJ SKSrt " “ the " 0VE S ‘ ate ’ y °“ 
down, left and soon. SiSl^r^td^STlt^ 

JSTiW SriS A ” C ° ntraCt tha —-ItogdMS'S 

described later in Ms ^iomf y definiti ° nS f<>r VT1 °° kayb ° ar ds are 

To scroll, move, expand, or contract a display: 

h fr^ S the y dMarSt ate<Uy ’ “ ne<,ded ' to S6leC ‘ * ha CUrrent scrollin S display 

2 - »4SScXS'Sir the default <scro,,) ’ 





. _ , D KV9 K p 4 KP6 and KP8 to do the desired function. Use the 

' PFHGOLD) and PF4 (BLUE) keys to control the amount of scrolling or 

movement. 



F18 

F19 

F20 


you mvoKe me aeuuggci. - 

Puts the keypad in the MOVE state, enabling the move-display functions o 
keys KP2, KP4, KP6, and KP8. 

Puts the keypad in the EXPAND state, enabling the expand-display functions 
of keys KP2, KP4, KP6, and KP8. 

Puts the keypad in the CONTRACT state enabling the contract-display 
functions of keys KP2, KP4, KP6, and KPS. 


, VT100 keyboard you can simulate the effect of LK201 keys F17 

If you have a VT10U keyboar , y BLUE-KP9 (currently 

to F20 by defining the key^equen^es preS sing 

undefined) as shown in the following code, vv: pressing BLUE-KP9 

GOLD-KW puts the keypad m*eMFAULT^UU^ P^8 N ^ CT 

cycles the keypad through the , Yo u ight wan t to store these key 

—ion «,e. 

D /TEEHfflME I KP9 T *SET ( KEY/STATE-»0»E/»0I«G" 


Inline Keypad Key Diagrams 


'online HELP for the keypad 
the PF2 key, either by itself or with other keys is 
the SHOW KEY command to identify key definitions. 




Table A -3 Keys that Invoke Online Help to Display Keypad Dlaorams 

Key or - : ----- 

Key Sequence 


Command Sequence Invoked 


Help 

PF2 

PF1-PF2 

PF4-PF2 

F18-PF2 

F18-PF1-PF2 

F18-PF4-PF2 

F19-PF2 

F19-PF1-PF2 

F19-PF4-PF2 

F20-PF2 

F20-PF1-PF2 

F20-PF4-PF2 


HELP KEYPAD SUMMARY 
HELP KEYPAD DEFAULT 
HELP KEYPAD GOLD 
HELP KEYPAD BLUE 
HELP KEYPAD MOVE 
HELP KEYPAD MOVE_GOLD 
HELP KEYPAD MOVE_BLUE 
HELP KEYPAD EXPAND 
HELP KEYPAD EXPAND_GOLD 
HELP KEYPAD EXPAND_BLUE 
HELP KEYPAD CONTRACT 
HELP KEYPAD CONTRACT_GOLD 
HELP KEYPAD CONTRACT_BLUE 


A.5 Debugger Key Definitions 

Table A-4 identifies all key definitions. 


Description 


Shows a diagram of the keypad keys and 

summarizes each key’s function 

fv, h ° W nt^l m ,° f the key P ad keys a nd 

their DEFAULT functions 

Shows a diagram of the keypad keys and 
their GOLD functions 

Shows a diagram of the keypad keys and 
their BLUE functions 

Shows a diagram of the keypad keys and 
their MOVE DEFAULT functions 

Shows a diagram of the keypad keys and 
their MOVE GOLD functions 

Shows a diagram of the keypad keys and 
their MOVE BLUE functions 

Shows a diagram of the keypad keys and 
their EXPAND DEFAULT functions 

Shows a diagram of the keypad keys and 
their EXPAND GOLD functions 

Shows a diagram of the keypad keys and 
their EXPAND BLUE functions 

Shows a diagram of the keypad keys and 
their CONTRACT DEFAULT functions 

Shows a diagram of the keypad keys and 
their CONTRACT GOLD functions 

Shows a diagram of the keypad keys and 
their CONTRACT BLUE functions 



KP1 


GOLD 


Command Invoked or Function 

STEP 
STEP/INTO 
STEP/OVER 

EXAMINE. Examines the logical successor of the 
current entity if one is defined (the next location). 

EXAMINE A . Enables you to examine the logical 
predecessor of the current entity, if one is defined 
(the previous location). 

(continued on next page) 
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KP2 DEFAULT 

GOLD 
BLUE 

MOVE 

MOVE_GOLD 

move_blue 

EXPAND 

EXPAND_GOLD 

expand_blue 

CONTRACT 
CONTRACT_GOLD 
CONTRACT_BLUE 
KP3 DEFAULT 

GOLD 

BLUE 


BLUE 

KP4 DEFAULT 

GOLD 
BLUE 

MOVE 

MOVE_GOLD 

MOVE_BLUE 

EXPAND 


Displays three sets of predefined process-specific 
source and instruction displays, SRC_n and 
INST_n. These consist of source and instruction 
displays for the visible process at S2 and RS2, 
respectively; source and instruction displays for the 
previous process on the process list at SI and Kbl, 
respectively; and source and instruction displays for 
the next process on the process list at S3 and Kbd, 
respectively. 

SCROLL/DOWN 

SCROLL/BOTTOM 

SCROLL/DOWN (not terminated). To terminate the 
command, supply the number of lines to be scrolled 
(:n) or a display name. 

MOVE/DOWN 
MOVE/DOWN :999 
MOVE/DOWN: 5 
EXPAND/DOWN 
EXPAND/DOWN :999 
EXPAND/DOWN :5 
EXPAND/DOWN1 
EXPAND/DOWN: 

EXPAND/DOWN 


-999 
-5 


SELECT/SCROLL %NEXTSCROLL. Selects as the 
current scrolling display the next display m the 
display list after the current scrolling display. 

SELECT/OUTPUT %NEXTOUTPUT. Selects the 
next output display in the display list as the current 
output display. 

Displays three predefined process-specific source 
displays, SRC_n. These are located at SI, til ,.and 
S3, respectively, for the previous, current (visible), 
and next process on the process list. 

SELECT/SOURCE %NEXTSOURCE. Selects the 
next source display in the display list as the current 
source display. 

SCROLL/LEFT 

SCROLL/LEFT:255 

SCROLL/LEFT (not terminated). To terminate the 
command, supply the number of lines to be scrolled 
(:n) or a display name. 

MOVE/LEFT 
MOVE/LEFT:999 
MOVE/LEFT: 10 
EXPAND/LEFT 

(continued on next page) 





Table A-4 (Cont.) Debu gger Key Definitions 
Key State 


KP5 


KP6 


KP7 


EXPAND_GOLD 
EXPAND_BLUE 
CONTRACT 
CONTRACT_GOLD 
CONTRACT_BLUE 
DEFAULT 


GOLD 

BLUE 

DEFAULT 

GOLD 

BLUE 

MOVE 

MOVE_GOLD 

MOVE_BLUE 

EXPAND 

EXPAND_GOLD 

EXPAND_BLUE 

CONTRACT 

CONTRACT_GOLD 

CONTRACT_BLUE 

DEFAULT 


GOLD 


EXPAND/LEFT:999 
EXPAND/LEFT: 10 
EXPAND/LEFT:-1 
EXPAND/LEFT:-999 
EXPAND/LEFT:-10 

EXAMINE/SOURCE .%SOURCE_SCOPE\ %pc- 
EXAMINE/INST .%INST_SCOPE\%PC. In line’ 
(noscreen) mode, displays the source line and 
the instruction to be executed next. In screen 
mode, centers the current source display on the 
next source line to be executed, and the current 
instruction display on the next instruction to be 
executed. 

SHOW CALLS 

SHOW CALLS 3 

SCROLL/RIGHT 

SCROLL/RIGHT:255 

SCROLL/RIGHT (not terminated). To terminate the 
command, supply the number of lines to be scrolled 
v-‘ n) or a display name. 

MOVE/RIGHT 

MOVE/RIGHT:999 

MOVE/RIGHT:10 

EXPAND/RIGHT 

EXPAND/RIGHT:999 

EXPAND/RIGHT: 10 

EXPAND/RIGHT:-1 

EXPAND/RIGHT:-999 

EXPAND/RIGHT:-10 

DISPLAY SRC AT LH1, INST AT RH1 OUT AT 

Irp S6 ’ select/scroll/source 

SRC, SELECT/INST INST; SELECT/OUT OUT 
Displays the SRC, INST, OUT, and PROMPT 
displays with the proper attributes. 

INST AT LH1, REG AT RH1, OUT AT 
P ^ t MPT AT S6; SELECT/SCROLL/INST 
INST; SELECT/OUT OUT. Displays the INST 

attributes^ ^ PR0MPT dis P la ys with the proper 


(continued on next page) 
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KP8 


KP9 


PF1 

PF2 

PF3 


State 

BLUE 


DEFAULT 

GOLD 

BLUE 

MOVE 

MOVE_GOLD 

move_blue 

EXPAND 

EXPAND_GOLD 

expand_blue 

CONTRACT 

CONTRACT_GOLD 

contract_blue 

DEFAULT 

GOLD 

BLUE 


DEFAULT 


GOLD 

BLUE 

PF4 

COMMA DEFAULT 


uomnidiiu iii vuiwm 

Displays two sets of predefined process-specific 
source and instruction displays, SRC_n and 
INST_n. These consist of source and instruction 
displays for the visible process at Q1 and RQ1, 
respectively, and source and instruction displays fo 
the next process on the process list at Q2 and KOA 
respectively. 

SCROLL/UP 

SCROLL/TOP 

SCROLL/UP (not terminated). To terminate the 
command, supply the number of lines to be scrolled 
(:n) or a display name. 

MOVE/UP 
MOVE/UP :999 
MOVE/UP:5 
EXPAND/UP 
EXPAND AJP:999 
EXPAND/UP: 5 
EXPAND AJP:-1 
EXPAND/UP:-999 
EXPAND/UP:-5 

DISPLAY %NEXTDISP. Displays the next display 
in the display list through its current window 
(removed displays are not included). 

SET PROCESS/VISIBLE %NEXT_PROCESS. 

Makes the next process in the process list the 
visible process. 

Displays two predefined process-specific source 

disdavs, SRC_n. These are located at Q1 and 04 
respectively, for the visible process and for the next 
process on the process list. 

See Table A-2. 

See Table A-3. 

SET MODE SCREEN; SET STEP NOSOURCE 
Enables screen mode and suppresses the output 
of source lines that would normally appear in the 
output display (since that output is redundant when 
the source display is present). 

SET MODE NOSCREEN; SET STEP SOURCE 
Disables screen mode and restores the output ot 
source lines. 

DISPLAY/GENERATE. Regenerates the contents of 
all automatically updated displays. 


See Table A—2. 
GO 


(continued on next page) 




BLUE 


MINUS DEFAULT 


GOLD 

BLUE 


Enter 

PERIOD 


Next 

Screen 

(E6) 

Prev 

Screen 

(E5) 

Remove 

(E3) 

Select 

(E4) 

F17 
F18 
F19 
F20 
Ctrl/W 
Ctrl/Z 


All states 

DEFAULT 

DEFAULT 

DEFAULT 

DEFAULT 


SELEC T/S 0U R C E %NEXT_SOURCE. Selects the 
^ceXpky 8 ^ “ ^ ^ Kst aS the « 

SELECT/INSTRUCTION %NEXTINST. Selects the 
c n ™T tn ‘,“ i< "; dis ;! ay in the lisTi^e 

current instruction display. 

DISPLAY %NEXTDISP AT S12345 PROMPT AT 
S6; SELECT/SCROLL %Cl*DI?P ’iSplf "hf 

next display in the display list at essentially full 
screen (top of screen to top of PROMPT display) 
Selects that display as the current scrolling display. 
Undefined. 

DISPLAY SRC AT HI, OUT AT S45 PROMPT AT 

SR C; SELECT 

/OUT OUT. Displays the SRC, OUT, and PROMPT 
dispkys W !th the proper attributes. This is the 
default display configuration. 

Xr nter < * ermin “ e)a Same 

f-SS- the effect of pressing state keys that do not 
lock the state, such as GOLD and BLUE. Does not 
attect the operation of state keys that lock the state 
such as MOVE, EXPAND, and CONTRACT. ’ 

SCROLL/DOWN 


SCROLL/UP 

DISPLAY/REMOVE %CURSCROLL. Removes the 
current scrolling display from the display list. 

SELECT/SCROLL %NEXTSCROLL. Selects as the 
current scrolling display the next display in the 
display list after the current scrolling display. 

See Table A-2. 

See Table A-2. 

See Table A-2. 

See Table A-2. 

DISPLAY/REFRESH 
EXIT 
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This appendix identifies all the debugger built-in symbols and logical names. 

B.1 SS$_DEBUG Condition 

s^S yi^ <* * «■»**■< y- can 

“ *» ~KeW& G anr 

gS “X commands to the debugger at the time you signal it with 

!^S“ S ^S-S^nce 

« ASCK sWng y0UI *»• devils on clSXg 

For example, to start the debugger and enter a SHOW pat t q 

S£St£Z7 ~ ““ m 

LIB$SIGNAL(SS$_DEBUG, 1, UPLIT BYTE(%ASCIC 'SHOW CALLS')); 

You can obtain the definition of SS$_DEBUG at comnile time f™™ 

SYSSLIBRARYSTj^IdSTOLB^this method is^lesis ££LS“ * 

B.2 Logical Names 

The following list identifies debugger-specific logical names: 



Specifies your debugger initialization file. Default- no 

or nartfJl ^ lallZat j on file ‘ DB G$INIT accepts a full 

Sectfon l2 2 e fr.r PeC f Catl ? n &S f® 11 as a search list - See 
Section 12.2 for information about debugger initialization 
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dbg$input 


DBG$OUTPUT 


DBG$PROCESS 

DBG$DECW$DISPLAY 


Specifies the debugger input device. Default: SYS$INPUT. 

See Section 13.2 for information about using DBG$INPU I 
and DBG$OUTPUT to debug screen-oriented programs at 
two terminals. 

DBG$INPUT is ignored the DECwindows Motifinlerfaee 
(see DBG$DECW$DISPLAY). You can use DBG$INPU 1 it 
you are displaying the debugger’s command interface 
DECterm window. 

Snpcifies the debugger output device. Default. 
SYS$OUTPUT. See Section 13.2 for information about using 
DBG$INPUT and DBG$OUTPUT to debug screen-onented 
programs at two terminals. 

DBG$OUTPUT is ignored in the DECwindowsMotifmterface 
(see DBG$DECW$DISPLAY). You can use D B G $ 0 U T PUJL 
if you are displaying the debugger’s command interface 
DECterm window. 

Specifies the debugging configuration (default or 
nmltiprocess). DeStf DBG$PROCESS 
Section 14.3.1 for information about using DBG$PKOCfc 
to specify the debugging configuration. 

Applies only to workstations running DECw md °Y s 
Motif. Specifies the debugger interface (DECwindows 
Motif or command) or the display device. Default. 
DBG$DECW$DISPLAY is either undefined or has the 
same definition as the application-wide logical name 
DECW$DISPLAY. 

See Section 2.7.3 for information about using 
DBG$DECW$DISPLAY to override the debugger s defau 
interface in the DECwindows Motif environment. 


initialization file: 

$ DEFINE DBG$INIT DISK?:[JONES.COMFILES]DEBUGINIT.COM 

Note the following point, about the logical name DBGtINPUT. If you plan to 
before starting the debugger. 

. , f. INPUT to point to the translation of SYS$COMMAND. If 

you define DBG$INPUT to point to SYS*COMMAND, the debugger tries to get 
its input from the file PROG_IN.DAT. 




B.3 Built-In Symbols 




Alpha 


“d valu^”’ 8 bUi “' in Symb ° IS Pr0Vide options fcr reifying program entities 

Most of the debugger built-in symbols have a percent sign (%) prefe 
The following symbols are described in this appendix: 

%NAME—Used to construct identifiers. 

%PARCNT—Used in command procedures to count parameters passed 

Motif interface was ^XS ^ “ mma ” d ,nterface » DECwindows 

• *BIN, %DEC, %HEX, %OCT-Used to control the input radix 

' = HHHSr ~ 

' »XO_ NAM E, *EXC_NUMBER. 

- K11Y Used t0 obtain information about exceptions. 

MOTE R l^Tft OTEY ^f I ^- SC0PE - ENTRY - ^PREVIOUS 

Se^ZSii^lt* 0 SP6C,fy CUrr “‘- —• “ d P-vious scope 
' %AP ' %FP ' %SP ' ^Used to 

’ ^ ™ vector 

%PP «*• ^P® Used to 

%P0 to %F30, %F31-Used to specify the Alpha floating-point registers. ♦ 

m^anismSfe^rcom^'^ee the'SS T argU ^ nt -P assin & 

the command dictionary. CALL command description in 

processes in mnltiprocess programs. See Section 1™ 2 *° Sp6Clfy 

' %NE ? T - TASK ' »PREVIOUS_TASK, 

niultfthmXm^SlSn ** * “ **■« - 

Stion ihu I l DTH ~ USed SPedfy the current scr «" height and width. See 
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Alpha 


• ssssssss=ss,:=s.rs i s;. 

in the display list. See Section 11.11.2. 

B.3.1 gymboi for a 

«:^ has not " “ Symb °' With 

*e same name. Table B-l identifies the VAX renter symbols. 



You can examine the contents of all the registers. You can deposit values into all 
the registers except for SP. Use caution when depositing values into . 

_ o <-• Q a an A Qpption 8 4 1 for more information about the VAX general 
Sst" Cha^r 15 for mote information about the VAX vector registers. . 

Table B-2 identifies the Alpha register symbols. 



%R0 ... %R28 
%FP (%R29) 
%SP (%R30) 
%R31 
%PC 


(continued on next page) 
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%F0 . . . %F30 
%F31 

On Alpha processors: 


Alpha Floating Point Registers 

Registers FO . . . F30 
ReadAsZero/Sink 


You cannot deposit a value into registers R31 or F 91 

assigned the value 0. are permanently 

• There are no vector registers. 

The debugger does not provide a screen-mode register display. 

SftTr?" 8 4 and & ' Cti ° n 8 ' 4 ' 2 information about the Alpha general 

B.3.2 Constructing Identifiers 

%NAME ’ character-string 1 

In the following example, the variable with the name ’12' la examined: 

DBG> EXAMINE %NAME '12' 

In the following example, the compiler-generated label P.AAA is examined: 

DBG> EXAMINE %NAME 'P.AAA' 

B.3.3 Counting Parameters Passed to Command Procedures 

a debugger command procedure). ( BAKCNT is defined only within 

r^nTpSur: b r f o,To“ pa , rametera passed *° 

invoked and three parameters are pfssST *' C ° mmand P ™ edura ABC.COM is 

DBG> @ABC 111,222,333 

Within ABC.COM, %PARCNT now has the value 3 %PARCNT ic +u , 
loop counter to obtain the value of each , ' / , KCIN 1 1S then used as a 

ue oi each parameter passed to ABC.COM- 

DBG> FOR I = 1 TO %PARCNT DO (DECLARE X:VALUE; EVALUATE X) 
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B 3 4 Determining the Debugger Interface (Command or DECwindows Motif) 

The %DECWINDOWS built-in symbol the 

debugger’s DECwindows Motif or command mterface d P ^ !ND0WS 
DECwindows Motif interface is being used he value of ^ 

is 1 (TRUE). When the command interface is bei g > 

%DECWINDOWS is 0 (FALSE). For example: 

dbg> evaluate %decwindows 

startup: 

IF %DECWINDOWS THEN , t „. . elini . av . 

! DECwindows Motif (workstation) syntax. 

(DISPLAY SRC AT (100,300,100,700)) 

ELSE 

i Screen-mode (terminal) syntax. 

(DISPLAY SRC AT (AT Hi)) 

“• “*£&.'T—. - sa.ssas- 

expressions and language expressions to sp^* ^alan [ at foUows) shou l d 

~r“°“ 

these radix built-in symbols only with integer literals. For examp . 

dbg> evaluate/DEC %HEX 10 
16 

DBG> EVALUATE/DEC %HEX (10 
32 

DBG> EVALUATE/DEC %BIN 10 

2 

DBG> EVALUATE/DEC %OCT (10 
16 

DBG> EVALUATE /HEX %DEC 10 
0A 

dbg> set radix decimal 

DBG> EVALUATE %HEX 20 + 33 
65 

DBG> EVALUATE IHEX (20+33) 

SbG> EVALUATE %HEX (20+ %OCT 10 +33) j J^ecimal^nd 10 as octal 
DBG> SYMBOLIZE %HEX 27C9E3 ! Symbolize a hexad<*Imal address 

“S iTrea^fddL ^5432 as'hexadecimL, and Operand 222 as decimal 

B 3 6 Snecifving Program Locations and the Current Value of an Entity 

LLowing built-in symbols enable you to specify program locations and the 
current value of an entity. 


+ 10 ) 


+ 10 ) 


Treat 20 as hexadecimal, 33 as decimal 
Resulting value is decimal _ 

Treat both 20 and 33 as hexadecimal 
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Symbol 


%NEXTLOC 
Return key 


Description 


%PREVLOC 
A (circumflex) 


%CURVAL 
\ (backslash) 


command * S * cornrnanc l terminator, it can be used only where a 
S- fe r r 18 appropriate (for example > immediately after 
/^dress’) b t n0t lmmedlately after DEPOSIT or EVALUATE 


d^iss *• raiue 12 is then 

current location: (WIDTH), this is verified by examining the 

DBG> EXAMINE WIDTH 
M0D\WIDTH: 7 
DBG> DEPOSIT . = 12 
DBG> EXAMINE . 

MOD\WIDTH: 12 
DBG> EXAMINE %CURLOC 
MOD\WIDTH: 12 
DBG> 

In the next example, the next and previous locations in an array are examined: 

DBG> EXAMINE PRIMES(4) 

M0D\PRIMES(4): 7 
DBG> EXAMINE %NEXTLOC 
M0D\PRIMES(5): 11 

Examine next location 

DBG> EXAMINE IPREVLOC 
MOD\PRIMES(5): 11 
DBG> EXAMINE A 
M0D\PRIMES(4) : 7 
DBG> 

2°£ tnlx^Ft^xfmS *** * ^ ^ SUCCessor does not apply 

command DEPOSIT to indicate the^ext Et the , Raturn key after ty Ping the 
symbol %NEXTLOC for that purpose. ^ bUt y ° U Can aIwayS use the 

Using Symbols and Operators in Address Expressions 



%LABEL 


label (for languages like FOOTRAN that h^TOnume^* 

p ™^ a ™ ba ! s) ; You c . an qualify the label with a path- 
ame prefix that specifies the containing module. 
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Backslash (\ ) 


At sign (@) 
Period (.) 


Bit field <p,s,e> 


Plus sign (+) 


Minus sign (-) 


Multiplication sign (*) 
Division sign (/) 


Specifies that the numeric literal that follows is a h^ 
number in your program. You can qualify the line numbe 
with a path name prefix that specifies the containing 
module. 

When used within a path name, delimits each element of 
the path name. In this context, the backslash cannot be 
the leftmost element of the complete path name. 

When used as the prefix to a symbol, specifies that the 
symbol is to be interpreted as a global symbol. In this 
context, the backslash must be the leftmost element of the 
symbol’s complete path name. 

Unary operators. In an address expression, the at 
sign (@) and period (.) each function as a contents-of 
operator The contents-of operator causes its operand to 
KSpreted as a memory address a n d thus request, the 
contents of (or value residing at) that address. 

Unary operator. You can apply bit field selection to an 
address-expression. To select a bit field, you supply a bit 
offset (p), a bit length (s), and a sign extension bit (e), 

which is optional. 

Unary or binary operator. As a unary operator, indicates 
the ^changed value of its operand. As a binary operator, 
adds the preceding operand and succeeding operand 
together. 

Unary or binary operator. As a unary operator indicates 
the negation of the value of its operand. As a binary 
operator, subtracts the succeeding operand from the 
preceding operand. 

Binary operator. Multiplies the preceding operand by the 
succeeding operand. 

Binary operator. Divides the preceding operand by the 
succeeding operand. 


The following examples show the use of built-in symbols and operators in address 
expressions. 

r'lrw-Jrctranrrrtracepomt at line 26 of the module in which 
execution is currently suspended. 

DBG> SET TRACE %LINE 26 

The next command displays the source line associated with line 47: 

dbg> EXAMINE/SOURCE %LINE 47 

m ° dUl 47 ^procedure SWAP(X,Y: in out INTEGER) is 
DBG> 

The next command sets a breakpoint at label 10 of module MOD4: 

dbg> SET BREAK M0D4\%LABEL 10 





Path-Name Operators 

The following command displays the value of the variable COUNT that 

declared m routine ROUT2 of module MOD4. The backslash 

delimiter separates the path-name elements: backslash < X > Path-name 

DBG> EXAMINE MOD4\ROUT2\CODNT 

MOD 4\R0UT2\COUNT: 12 

DBG> 

The following command sets a breakpoint on line 26 of the module QUEUMAN: 

DBG> SET BREAK QUEUMAN\%LINE 26 

The following command displays the value of the global symbol X: 

DBG> EXAMINE \X 

Arithmetic Operators 

element8 i an aidiess 

by the following three factors listed in d 8 ^ ngua ® es ' T ^ le or der is determined 
have higher precetocet decreasmg order of precedence (first listed 

L XZSSZSS?*' “ *» operands 

2- The assignment of relative priority to each operator 
3. Left-to-right priority of operators 

The debugger operators are listed in decreasing order of precedence as follows: 

1. Unary operators (., +, .) 

2. Multiplication and division operators (*, /) 

3. Addition and subtraction operators (+ -) 

5-(T+5)/4 

x:l°"Z ng COmma ” d diSPkyS ^ ^ C ° ntaine<1 in the location 

DBG> EXAMINE X + 4 

Contents-of Operator 

==5SSSS2£=tRS5SSSs= 

DBG> EXAMINE .%PC 
M0D\%LINE 5: PUSHL S A #8 
DBG> 

gained ZSZSZZSL*£££" P ° ~ ■"* «- call *ack 

DBG> EXAMINE/SOURCE .1\%PC 
module MAIN 

MAIN\%LINE 134: SWAP(XY)- 

DBG> 
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For the next cample, thevalue «£&£ — "TvTue of 

Jto SFFOOOTOhexadecimal. The following command shows how to 

examine the entity: 

dbg> examine/long .PTR 

7FF00000: 3FF00000 

Tthe next example, the contents-of operator (at sigr, or period) is usedwith the 
current location operator (period} to examine a in following figure), 

integer pointer vfriable 

variable; the high Jongword o, each variable 
contains its integer value (8, 6, and 12, respective y). 


P: 



ZK-7936-GE 


dbg> SET TYPE QUADWORD; set 
dbg> examine .p 

00009BC2: 00000008 00009BDA 
DBG> EXAMINE @. 

00009BDA: 00000006 00009BF4 
DBG> EXAMINE .. 

00009BF4: 0000000C 00000000 


RADIX HEX 

i Examine the entity whose address 
! is contained in P. 

! High word has value 8, low word 
! has address of next entity (9BDA). 

! Examine the entity whose address 
! is contained in the current entity. 

! High word has value 6, low word 
! has address of next entity (9BF4). 
i Examine the entity whose address 
! is contained in the current entity. 

! High word has value 12 (dec.), low word 
1 has address 0 (end of list). 


and no sign extension, enter the following command: 

DBG> EXAMINE X_NAME <3,4,0> 

o o o ohtainina Information About Exceptions 

Description 

Name of facility that issued the current exception 
Name of current exception 

Ada exception name of current exception (for Ada programs only) 


Symbol 

%EXC_FACILITY 

%EXC_NAME 

%ADAEXC_NAME 
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%EXC_NUMBER 

%EXC_SEVERITY 

For example: 


Number of current exception 
Severity code of current exception 


DBG> EVALUATE %EXC NAME 
"FLTDIV_F" ~ 

DBG> SET BREAK/EXCEPTION WHEN (%EXC_NAME = 


"FLTDIV_F") 


DBG> EVALUATE %EXC NUMBER 
12 

DBG> EVALUATE/CONDITION VALUE %EXC NUMBER 

—- 

The conditional expressions in the WHEN clauses are language-specific. 

Specifying the Current, Next, and Previous Scope on the Call Stack 


%NEXT_SCOPE_ENTRY 

%PREVIOUS_SCOPE_ENTRY 


The call frame that the debugger is currently using 
as reference when displaying source code or decoded 
ratradaons, ° r searchin g for symbols. By 
default, this is call frame 0. 

The next call frame down the call stack from the call 
frame denoted by %CURRENT_SCOPE_ENTRY. 

The next call frame up the call stack from the call 
frame denoted by %CURRENT_SCOPE_ENTRY 


SSSSSSSSSEr—“ 


DBG> SET SCOPE/CURRENT %NEXT_SC0PE ENTRY 
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SST 1,86 the debugger with programs written in the 

BLISS c 


Ada 

C++ 1 

MACRO-32 
SCAN 


BASIC 

COBOL 

Pascal 


DIBOL 

PL/I 


FORTRAN 

RPGII 


'Note that C++ functionality is minimal in this release. 

followingDEclanguages: ° an ” ‘ he debUgger " ith » r0grams * ‘he 

Ada^ BASIC BLISS C 

C++ COBOL Fortran MACRO-32 2 

MACRO-64 Pascal pxyj 

'Note that C++ functionality is minimal in this release. 

Note that MACRO-32 must be compiled with the AMACRO compiler. 

™ppXdfJ™g^ S C”f g ? ng teC ^, iqUeS tha ‘ are common -oot of the 

is specmc to ^hTan Jage 8 ^ Pr0Vide further info ™ a ‘ i ° p ‘hot 


C.1 Overview 


lln^ae^It akn 08111268 ^ Sy ^ tax ’ data typing, and scoping rules of each 
Therefore whon reC0 ^ S each lan ^age’s operators and expression syntax 

• Supported operators in language expressions 

Supported constructs in language expressions and address expressions 

• Supported data types 

1 aT age ' SPeCi& inf0 ™ ati °". “ng restrictions in debugger 

• -r to the 
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C.2 ADA 


C.2.1 


SSSSSISatSsSSSsSas 

choice. 

On VAX processors, you can specify one of the following keywords. 

ADA BASIC BLISS c 

C_PLU S_PLU S COBOL DIBOL FORTRAN 

MACRO PASCAL PLI RPG 

SCAN UNKNOWN 

On Alpha processors, you can specify one of the following keywords: 

ADA AMACRO C C_PLUS_PLUS 

COBOL FORTRAN MACRO MACR064 

PASCAL UNKNOWN 

wSn F ^ £2 ™w»n. - >-» 

on Language_UNKNOWN. 

The following subtopics deBcribe debugger support for Ada. For information 
specific toAda tasking programs, see also the debugger manual. 

Ada Names and Symbols 

The following subtopics describe debugger support for Ada names and symbo , 
including predefined attributes. 

Note that parts of names may be language expressions—for e^mp^^tributes 

- „ c .pTDcrn >pos This affects how you use the EXAM INK, Kval 
S —ds with such names. For examples of enumerate types, 

see help on Specifying_Attributes_with_Enumeration_Types. 
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C.2.1.1 Ada Names 

Supported Ada names follow: 



Full support for Ada rules for the syntax of identifiers. 
Function designators that are operator symbols (for examnle 

“ rs r* is; fk ' 

M to”k» ° Pera, ° r ”“ st <» in 

Full support for Ada rules for numeric literals, character 
literals, string literals, and reserved words. 

SimteSS 1 faleser literak to *■“ ™»«» 

Depending on context and architecture, the debugger 
nterprets floating-point types as F_floating, D_fl«fating 
G_floating, H_floatmg, S_floating, or T_floating. g ’ 

Full support. 

eValUate “ enti ” Sii “ ° r “ i “ to “ d 

cZT d eSln1^,ii deX ‘' , COmP ° nmt ° fa S "“- Y »" 

Full support, including use of the keyword all in .all. 

Full support, including the keyword null. 

Full support (TRUE, FALSE). 

^EXAMI^pV 116 en ‘ ire v reCOrd and arra y objects with 
me EXAMINE command. You can deposit a value in a 

DETOSIT a r ¥ ::. r record ' You '“not «" the 
character^strtoj^vahies agg " gatel ' *» d «P«*it 


C.2.1.2 Predefined Attributes 

attributes follow. Note that the debugger SHOW 
P'FIRST, P'LAST^™^NGlH^P^SIM, a |^^ 1 ^NSTRAJ}^D P ^tributesf ^ 


Indexed components 
Slices 


Selected components 
Literals 

Boolean symbols 
Aggregates 


P'FIRST 
P' FIRST 

P'FIRST(N) 

P' LAST 


The a vaTu?ofP'CONSTIMINp r n COr fl W**™* discriminants. 
(constra"e°d f o P r S2SST ^ ° f P 

For a prefix P that denotes an enumeration type or a subtvne of 
an enumeration type. Yields the lower bound of P. ^ 

For a prefix P that is appropriate for an array type or that 

‘ UTay SUbtyPe ' Yislds “» low « r bound of 

dpnnt PrCfiX P , that is a PPmpriate for an array type or that 
the S M array SUb ‘ ype ■ Y “ lda * h « l»"nd of 

For a prefix P that denotes an enumeration type or a suhtvno «f 
an enumeration type. Yields the upper bound ofP ^ ° f 
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P' LAST 

P' LAST(N) 

P' LENGTH 

P'LENGTH(N) 

P'POSCX) 

P'PRED(X) 

P' SIZE 
P'SUCC(X) 

P'VAL(N) 


For a Drefix P that is appropriate for an array type, or that 
denotesaconstrained a™, subtype. Yields the upper bound of 
the first index range. 

For a Drefix P that is appropriate for an array type, or that 
denotes aconstrained aSay subtype. Yields the upper bound of 
the Nth index range. 

of the first index range (zero for a null range), 
of the Nth index range (zero for a null range). 

For a Drefix P that denotes an enumeration type or a subtype of 
In enumeTaton type. Yields the position number of the value X. 
The first position is 0. 

For a Drefix P that denotes an enumeration type or a subtype 
of an enumeration type. Yields the value of type P winch has a 
position number one less than that ot a. 

For a prefix P that denotes an object. Yields the number of bits 
allocated to hold the object. 

For a Drefix P that denotes an enumeration type or a subtype 
If anderation typo. Yrolds the value of type F wh.ch has a 
position number one more than that ot A. 

For a Drefix P that denotes an enumeration type or a subtype of 
USto type. Yields the value of type P wh.ch has the 
position number N. The first position is . 


C.2.1.2.1 Specifying Attributes with Enumeration Types 

declarations: 


Consider the following 


^^MONDAyItUESDAY, WEDNESDAY, THURSDAY, FRIDAY, SATURDAY, SUNDAY!; 

MY_DAY : DAY; 

The following examples shSivST 

on the right of the := operator in a DEPOSIT comman . 

DBG> EVALUATE DAY'FIRST 
MON 

DBG> EVALUATE DAY'POS(WEDNESDAY) 

2 

DBG> EVALUATE DAY'VAL(4) 

FRI 

DBG> DEPOSIT MY_DAY := TUESDAY 
DBG> EVALUATE DAY'SUCC(MY_DAY) 

WED 

DBG> DEPOSIT . := DAY' PRED (MY_DAY) 

DBG> EXAMINE . 

EXAMPLE.MY DAY: MONDAY 

DBG> EVALUATE DAY' PRED (MY_DAY) 

%DEBUG-W-ILLENUMVAL, enumeration value out of leg g 
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C.2.2 


C.2.2.1 


“to'L1“°' Vin9 OVer,0a<,e<, EnUmera,i0n <-"*'*'* Consider the following 

type MASK is (DEC,FIX,EXP); 
type CODE is (FIX,CLA,DEC); 

MY_MASK : MASK; 

MY_CODE : CODE; 

DBG> DEPOSIT MY_CODE := FIX 

IDEBKG-HOIIODE, symbol 'FIX' is not uniaue 
DBG> SHOW SYMBOL/TYPE FIX ^ 

data EXAMPLE.FIX 

dat, 8 £S m tyPe <C0DE ' 3 eientents l'( size: 1 byte 

88 “cLMir” 181 ' !lze: 1 byte 

DBG> EXAMINE MY CODE 
EXAMPLE.MY_C0DE7 FIX 

Operators and Expressions 

The following subtopics desribe debugger sunuort for ATYA . 

language expressions.describe debugger sunnort for Ado op ® rators a “ d 
expressions. gg su PP° rt tor Ada operators and language 

Operators in Language Expressions 

Supported Ada operators in language expressions follow: 


Kind 

Prefix 

Prefix 

Syml 

+ 

Infix 

+ 

Infix 

_ 

Infix 

* 

Infix 

/ 

Infix 

MOD 

Infix 

REM 

Infix 

** 

Prefix 

ABS 

Infix 

& 

Infix 

— 

Infix 

/= 

Infix 

> 

Infix 

>= 

Infix 

< 


Function 

Unary plus (identity) 

Unary minus (negation) 

Addition 

Subtraction 

Multiplication 

Division 

Modulus 

Remainder 

Exponentiation (VAX specific) 

Absolute value 

Concatenation (only string types) 

Equality (only scalar and string types) 

Inequality (only scalar and string types) 

Greater than (only scalar and string types) 

Greater than or equal (only scalar and string types) 
Less than (only scalar and string types) 
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Kind 

Infix 

symooi 

<= 

Less than or equal (only scalar and string types) 

Prefix 

NOT 

Logical NOT 

Infix 

AND 

Logical AND (not for bit arrays) 

Infix 

OR 

Logical OR (not for bit arrays) 

Infix 

XOR 

Logical exclusive OR (not for bit arrays) 


The debugger does not support the following items: 

• Operations on entire arrays or records 

• The short-circuit control forms: and then, or else 

• The membership tests: in, not in 

• User-defined operators 

C.2.2.2 Language Expressions 

Supported Ada expressions follow 

Debugger Support 


Type conversions 


No support for any of the explicit type conversions specified 
in Ada P However, the debugger performs certain implicit type 
conversions between numeric types during the evaluation of 
expressions. 

The debugger converts lower-precision types to higher-precision 
types before evaluating expressions involving types of different 
precision: 

• If integer and floating-point types are mixed, the integer 
type is converted to floating-point type. 

. If integer and fixed-point types are mixed, the integer type 
is converted to fixed-point type. 

• If integer types of different sizes are mixed (for example, 
byte-integer and word-integer), the one with the sma e 
size is converted to the larger size. 


Subtypes 

Qualified expressions 


Allocators 

Universal expressions 


Full support. Note that the debugger denotes subtypes and 
types that have range constraints as subrange types. 

SuDDorted as required to resolve overloaded enumeration 
literals (literals that have the same identifier but belong to 
different enumeration types). The debugger does no supp 
qualified expressions for any other purpose. 

No support for any operations with allocators. 

No support.__ 
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C.2.3 Data Types 

Supported Ada data types follow: 


Ada Data Type 

INTEGER 

SHORTJNTEGER 

SHORT_SHORT_INTEGER 

SYSTEM.UNSIGNED_QUADWORD 

SYSTEM.UNSIGNED_LONGWORD 

SYSTEM. UNSIGNED_WORD 

SYSTEM.UNSIGNED_BYTE 

FLOAT 

SYSTEM.F_FLOAT 

SYSTEM.D_FLOAT 

LONG_FLOAT 


SYSTEM.G_FLOAT 

SYSTEM.H_FLOAT 
(VAX specific) 

LONG_LONG_FLOAT 
(VAX specific) 

IEEE_SINGLE_FLOAT 

(Alpha specific) 

IEEE_DOUBLE_FLOAT 

(Alpha specific) 

Fixed 

STRING 

BOOLEAN 

BOOLEAN 

Enumeration 


Arrays 

Records 

Access (pointers) 
Tasks 


operating System Data Type Name 


Longword Integer (L) 

Word Integer (W) 

Byte Integer (B) 

Quadword Unsigned (QU) 

Longword Unsigned (LU) 

Word Unsigned (WU) 

Byte Unsigned (BU) 

F_Floating (F) 

F_Floating (F) 

D_Floating (D) 

if P 1-3 ®” 13 LONG_FLOAT 
(D_FLOAT) is in effect. G_Floating (G) 

effect^ 3 L0NG - FL0AT (G-FLOAT) is’in 

G_Floating (G) 

H_Floating (H) 

H_Floating (H) 

S_Floating (FS) 

T_Floating (FT) 


(None) 

ASCII Text (T) 

Aligned Bit String (V) 

Unaligned Bit String (VU) 

For any enumeration type whose value fits 
into an unsigned byte or word: Byte Unsigned 
(BU) or Word Unsigned (WU), respective^ 
Otherwise: No corresponding operating 
system data type. 

(None) 

(None) 

(None) 

(None) 


C.2.4 Compiling and Linking 

The Ada predefined units in the ADA^PRFnn’P'Tivnm i ., 

system have been compiled with the /NODEBU^mmrfi™^? 11 ^ 1 ^ 17 ° n y0Ur 

debugger to refer to names declared in 1thenred * Before USing the 

the predefined unit source files using the ACS EXT^CT SmmpT^ firSt C ° Py 
Then, you must compile the conies intoThf* 'SOURCE command. 

qualifier, and relink the program with t^ ** the 
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SSSiSSs 

languages by means of the Ada export pragmas. 

EXPORT_PROCEDURE 

EXPORT_VALUED_PROCEDURE 

EXPORT.FUNCTION 

EXPORT_OBJECT 

EXPORT_EXCEPTION 

PSECT_OBJECT 

image. 

C.2.5 S0Ur “^ e P ^ e may not ^ avaUable for display for the following reaeons that are 
specific to Ada programs: 

. Execution is paused within Ada initialisation or elaboration code, for wh,ch 
no source code is available. 

. The copied source Ale is not in the program library where the unit was 
originally compiled. 

. The external source file is not where it was when the unit was origina y 
compiled. 

The following paragraphs explain how to control the display of source code wrth 

Ada programs. . . 

/pr>PY SOURCE q ualifi er (the default) was in enect 

units. , , . 

The Ale sP^'^cations of the copicxUu e^mal^ource^es^m^embed^|^^ 

entire ^‘atertp^Snal Se^odiAed o7the origina, 
source files. If, after copying J nQt find the origina l copied source 

moved?he externa, source Ales to another disk or 

directory, the debugger may not find them. 

In such cases, use the SET Jjj-^ 

ZrZ £f dirSrS! ^example (ADA$LIB is the logjcal^ame that the 
program library manager equates to the current program 1 

D bG> SET SOURCE ADA$LIB,DISK:[SMITH.SHARE.ADALIB] 
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files that the debuggerfetches d wLn°vou feCt *+]? Hst f ° r the external s °urce 

tell the EDIT commfnd where ^ w the debugger EDIT C0I ™and. To 
/edit command. k f ° r y ° Ur S0Urce files > use the SET SOURCE 

C.2.6 EDIT Command 

fetches the " 

is currently paused You do not edit tVm • mpiIatl0n umt in which execution 
tha, the debugger J“„r 3^ dismay " fi ‘ e ’ ^ ‘ >rogram 

files have been located after compiiaLt, L S^^SiST 

f T fWRCIVEDIT command to specify 
files. For example: where he debugger should look for source 

DBG> SET SOURCE/EDIT [],USER:[JONES.PROJ.SOURCES] 

source files B * Udl f ° r COpied 

being used Me'SOURCE/E dTtc 
re^t& being -d for the EDIT command and 

C.2.7 GO and STEP Commands 

Note the following points about using the GO anH <?TFP ~ , 

programs: g nd bTEP commands with Ada 

• ssrsui;a^^scrsssas. 

Debugging^da_Ifibrary^Packages. ****** elaboration Phase, see help on 

If a line contains more than one statempnt Q qtpp 

statements on that line as part of a single^tep eXecutes ““ 

ent^SlsTrc q C u a euedand 0 M he “T" “ 3ubpr ‘« ram «>"s because task 
command to move eaerafton inm"a t^^ ngh ‘ aWay - If you use ‘he STEP 
what you exp™ 8 ta * k entry ca »- th «> ™enlt» might not be 
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“* -j3sss.au 

"rml'^am i exSd Library specifications, bodies, and some of 
their subunits are also elaborated by this process. 

The elaboration of library packages accomplishes the following operations: 

• Causes package declarations to take effect 

. Initializes any variables whose declaration includes initialization code 
. Executes any sequence of statements that appear between the begm and en 

statements of package bodies 

executed ^of 

library units. For example: 

%MBUG-I-INITIAL, language is ADA^ module ^f^ogram 
%DEBUG-I-NOTATMAIN, type GO to get to start or v y 

DBG> 

At that point, before typing GO to 

step through and examine in You then use the GO 

SnTbSr: ea* Package 

a trailing underscore character (_). 

(see help on the Setting_Modules subtopic). 

Also, to set a breakpoint on a subprogram declared in a package specification, you 
must set the module for the package body. 

Note that the compiler generates.™,.*^ 

subtopic. 


C.2.9 Predefined Breakpoints 


‘tinea DreaKpumo 

When you start the debugger with an Ada P™P»m(o™ S 

that calls Ada code), two breakpom These breakpoints are established 

—thSle b Ada run-time library is 

present. 
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C.2.10 


C.2.10.1 


C ° mmand , “ der theS6 “ nditions - *• 

DBG> SHOW BREAK 

Pre defi n ed^breakp° int on ADA event "EXCEPTION_TERMINATED" 

Pred for n an ^alue 0 ^ ^ A ° A 6Vent " DEPENDENTS _ EXCEp TION" 

DBG> 

Monitoring Exceptions 

The debugger recognizes three kinds of exceptions in Ada programs: 

i^ er ;? efined exc A e P tion — an exception declared with the Ada reserved word 
exception m an Ada compilation unit 

ERROR Predefined exception > such as PROGRAM_ERROR or CONSTRAINT. 

Any other (non-Ada) exception or condition 
The following subtopics explain how to monitor such exceptions. 

Monitoring Any Exception 

The SET BREAK/EXCEPTION command enables you to set a breakpoint 
on any exception or condition. This includes certain conditions that are 
ignaled internally within the Ada run-time library. These conditions are an 
implementation mechanism; they do not represent program failures and thev 

r a t b dl andled ^ exception ha ndlers. If these conditions appeal while 

Lep,i„„: b „r„i^s a zr may want to “ nsider *• kind 

DBG> SET TRACE/EXCEPTION 
DBG> GO 

-5ADA-F-C0NSTRAINT_ERR0, CONSTRAINT ERROR 

-ADA-I-EXCRAIPRI, Exception raisecTprior to PC = 00000A7C 
trace on exception preceding 

ADA$RAISE\ADA$RAISE__CONDITION.%LINE 333+12 

SH ° W < t ALU \ comm “ d a traceback of the 

exeephon wasrated Wam Where ““ eXCepti ° n the 

DBG> SET BREAK/EXCEPTION DO (SHOW CALLS) 

DBG> GO 

^SYSTEM-F-INTDIV, arithmetic trap, integer divide 
by zero at PC=000008AF, 

PSL=03C000A2 break on exception preceding 
SYSTEM_OPS.DIVIDE.%LINE 17+6 
17: return X/Y; 
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module name routine name 

♦SYSTEM OPS DIVIDE 

♦PROCESSOR PROCESSOR 

*ADA$ELAB PROCESSOR 

ADA$ELAB_PROCESSOR 
LIB$INITIALIZE 

SHARE$ADARTL 
*ADA$ELAB PROCESSOR 

ADA$ELAB_PROCESSOR 
LIB$INITIALIZE 


line rel PC 
17 00000015 

19 000000AE 

00000009 

00000054 

00000000 

0000001B 

0000002F 


abs PC 
000008AF 
00000BAD 

00000809 

00000C36 

000398BE 

0000081B 

00000C21 


In this example, the condition SS$_INTDIV is raised at line 17 of the subprogram 
DIVIDE in the package SYSTEM_OPS. The example shows an important effect, 
some conditions (such as SS$_INTDIV) are treated as being equivalent to some 
Ada predefined exceptions. 

The matching of a condition and an Ada predefined exception is performed by the 
condition handler provided by Ada for any frame that includes an exception pa . 
Therefore when an exception breakpoint or tracepoint is triggered by a condition 
that has an equivalent Ada exception name, the message displays only the syste 
condhfonTodename, and not the name of the corresponding Ada exception. 

C.2.10.2 the debugs sets the Mowing ^ 

“se them to qualify exception breakpoints or tracepomts so that they 
trigger only on certain exceptions. 

A string that names the facility that issued the exception The 
facility name for Ada predefined exceptions and user-defined 
exceptions is ADA. 

An uppercase string that names the exception. If the exception 
raised is an Ada predefined exception, its name is truncated 
if it exceeds 15 characters. For example, CONSTRAIN 1_ 

ERROR is truncated to CONSTRAINT_ERRO If the exception 
is a user-defined exception, %EXC_NAME contains the string 
"EXCEPTION", and the name of the user-defined exception is 
contained in %ADAEXC_NAME. 

If the exception raised is user-defined, %ADAEXC NAME contains 
a string that names the exception, and %EXC JSTAME contains 
the string "EXCEPTION". If the exception is not user-defined 
%ADAEXC_NAME contains a null string, and the name of the 
exception is contained in %EXC_NAME. 

The number of the exception. 

A string that gives the exception severity level (F, E, W, I, S, or ?). 


%EXC_FACILITY 

%EXC_NAME 


%ADAEXC_NAME 


%EXC_NUM 
%EXC_SEVERITY 


C 2 10 3 Monitoring Handled Exceptions and Exception Handlers 

C.2.10.O wio 9 and SET TRA ce/EVENT commands let you set 

toeaSnfaSiTacepomts on exceptions that are about to be handled by Ma 
except handlers. These commands let you observe the executmn of each Ada 
exception handler that gains control. 

You can specify two event names with these commands: 


HANDLED 

HANDLED_OTHERS 


Triggers when an exception is about to be handled in some Ada 
exception handler, including an others handler. 

Triggers only when an exception is about to be handled in an 
others Ada exception handler. 
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For example, the following command sets a breakpoint that triggers whenever an 
exception is about to be handled by an Ada exception handler: 

DBG> SET BREAK/EVENT=HANDLED 

When the breakpoint triggers, the debugger identifies the exception that is about 
to be handled and the exception handler that is about to be executed. You can 
then use that information to set a breakpoint on a particular handler, or you can 
enter the GO command, and see which Ada handler next attempts to handle the 
exception. For example: 

DBG> GO 

break on Ada event HANDLED 

task %TASK 1 is about to handle an exception 
The Ada exception handler is at: PROCESSOR.%LINE 21 
%ADA-F-CONSTRAINT_ERRO, CONSTRAINT_ERROR 
-ADA-I-EXCRAIPRI, Exception raised prior to PC = 00000A7C 
DBG> SET BREAK PROCESSOR.ILINE 21; GO 

C.2.11 Examining and Manipulating Data 

When examining and manipulating data, note the following considerations: 

Before you can examine or deposit into a nonstatic variable (any variable not 
declared in a library package), its defining subprogram, task, and so on, must 
be active on the call stack. 

• Before you can examine, deposit, or evaluate an Ada subprogram formal 
parameter or an Ada variable, the parameter or variable must be elaborated. 
In other words, you should step or otherwise move execution past the 
parameter or variable’s declaration. The value contained in any variable or 
formal parameter whose declaration has not been elaborated might be invalid. 

In most cases, the debugger enables you to specify variables and expressions in 
debugger commands exactly as you would specify them in the source code of the 
program, including use of qualified expressions. The following subtopics discuss 
some additional points about debugger support for records and access types. 

C.2.11.1 Records 

Note the following points about debugger support for records: 

• With certain Ada record variables, the debugger fails to show the record 
components correctly (possibly with a NOACCESSR error message) when the 
type declaration is in a different scope than the record (symbol) declaration. 

• With variant records, the debugger lets you examine or assign a value to 
a component of a variant part that is not active. But because this is an 
illegal action in Ada, the debugger also issues an informational message. For 
example, assume that record REC1 has a variant field named STATUS and 
that the value of STATUS is such that REC1.COMP3 is inactive: 

DBG> EXAMINE REC1.C0MP3 

IDEBDG-I-BADDISCVAL, incorrect value of 1 in discriminant 
field STATUS 
MAIN.REC1.COMP 3: 438 
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C.2.11.2 Access Types 

Note the following points about debugger support for access types: 

• The debugger does not support allocators, so you cannot create new access 
objects with the debugger. 

• When you specify the name of an access object with the EXAMINE command, 
the debugger displays the memory location of the object it designates. 

• To examine the value of a designated object, you must use selected component 
notation, specifying .ALL. For example, to examine the value of a record 
access object designated by A: 

DBG> EXAMINE A.ALL 
EXAMPLE.A.ALL 

NAME(1..10): "John Doe " 

AGE : 6 

NEXT: 1462808 

• To examine one component of a designated object, you can omit .ALL from the 
selected component syntax. For example: 

DBG> EXAMINE A.NAME 

EXAMPLE.A.ALL.NAME(1. .10): "John Doe " 

The following example shows the debugger support for incomplete types. Consider 
the following declarations: 

package P is 

type T is private; 
private 

type T_TYPE; 

type T is access T_TYPE; 
end P; 

package body P is 
type T_TYPE is 
record 

A: NATURAL := 5; 

B: NATURAL := 4; 

end record; 

T REC: T_TYPE; 

T PTR: T := new T_TYPE'(T_REC); 

end P; 

with P; use P; 
procedure INCOMPLETE is 
VAR: T; 
begin 

end INCOMPLETE; 

The debugger does not have complete information about the type T, so you cannot 
manipulate the variable VAR. However, the debugger does have information about 
objects declared in the package body P. Thus, you can manipulate the variables 
T_PTR and T_REC. 
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C.2.12 Module Names and Path Names 

The names of Ada debugger modules are the same as the names of the 
corresponding compilation units, with the following provision. To eliminate 
ambiguity, an underscore character (_) is appended to a specification name 
to distinguish it from its body name. For example, TEST (body) TEST_ 
(specification). To determine the exact names of the modules in your program 
use the SHOW MODULE command. * 

In most cases when you specify a path name the debugger can distinguish body 
names and specification names from the context. Therefore, use this naming 
convention only if needed to resolve an ambiguity. 

When the debugger language is set to Ada, the debugger generally constructs 
pathnames that follow the Ada rules, using selected component notation to 
separate path name elements (with other languages, a backslash is used to 
separate elements). For example: 


TEST_.A1 

TEST.B1 


! A1 is declared in the package 
! specification of unit TEST 
! B1 is declared in the package 
! body of unit TEST 


The maximum length that you can specify for a subunit path name (expanded 
name) is 247 characters. F 

When a use clause makes a symbol declared in a package directly visible outside 
the Package you do not need to specify an expanded name (package-name.symbol) 
to refer to the symbol, either in the program itself or in debugger commands. 

The SHOW SYMBOL/USE_CLAUSE command identifies any package (library 
or otherwise) that a specified block, subprogram, or package mentions in a use 
clause. If the entity specified is a package (library or otherwise), the command 
also identifies any block, subprogram, package, and so on, that names the 
specified module in a use clause. For example: 

DBG> SHOW SYMBOL/USE_CLAUSE B_ 
package spec B_ 
used by: F 
uses: A 

If a label has been assigned to a loop statement or declare block in the source 
code, the debugger displays the label; otherwise, the debugger displays LOOP$n 
for a loop statement or BLOCK$n for a declare block, where n is the line number 
at which the statement or block begins. 

C.2.13 Symbol Lookup Conventions 

For Ada programs, when you do not specify a path name (including an Ada 
expanded name), the debugger searches the run-time symbol table as follows. 

1. The debugger looks for the symbol within the block or routine surrounding 
the current PC value (where execution is currently paused). 

2. If the symbol is not found, the debugger then searches any package that 
is mentioned in a use clause. The debugger does not distinguish between 
a ibrary package and a package whose declaration is in the same module 
as the current scope region. If the same symbol is declared in two or more 
packages that are visible, the symbol is not unique (according to Ada rules) 
and the debugger issues a message similar to the following: 

%DEBUG-E-NOUNIQOE, symbol 'X' is not unique 


C-15 




3. If the symbol is still not found, the debugger searches the call stack and other 
scopes, as for other languages. 


C.2.14 Setting Modules 

When you or the debugger sets an Ada module, by default the debugger also sets 
any “related” module (that is, any module whose symbols should be visible within 
the module being set). Such modules are related to the one being set through 
either a with-clause or a subunit relationship. 


Related module setting takes place as follows. If Ml is the module that is being 
set, then the following modules are considered related and are also set: 


• If Ml is a library body, the debugger also sets the associated library 


specification, if any. 

• If Ml is a subunit, the debugger also sets its parent unit and, therefore, any 
parent of the parent. 

• If Ml mentions a library package PI in a with clause, the debugger also sets 
Pi’s specification. Neither the body of PI nor any possible subunits ol PI are 
set, because symbols declared within them should not be visible outside. 

If Pi’s specification mentions a package P2 in a with clause, the debugger 
also sets P2’s specification. Likewise, if P2’s specification mentions a package 
P3 in a with clause, the debugger also sets P3’s specification, and so on. The 
specifications of all such library packages are set so that you can access data 
components (for example, record components) that may have been declared in 

other packages. 


• If Ml mentions a library subprogram in a with clause, the debugger does 
not set the subprogram. Only the subprogram name needs to be visible in 
Ml (no declaration within a library subprogram should be visible outside 
the subprogram). Therefore, the debugger inserts the name of the library 
subprogram into the RST when Ml is set. 

If debugger performance becomes a problem as more modules are set, use the 
SET MODE NODYNAMIC command which disables related module setting as 
well as dynamic module setting. You must then set individual modules explicitly 
with the SET MODULE command. 


By default, the SET MODULE command sets related modules simultaneously 
with the module specified in the command. 

The SET MODULE/NORELATED command sets only the modules you specify 
explicitly. However, if you use SET MODULE/NORELATED, you may find that a 
symbol which is declared in another unit and which should be visible at the pom 
of execution is no longer visible; or that a symbol which should be hidden by a 
redeclaration of that same symbol is now visible. 


The CANCEL MODULE/NORELATED command deletes from the RST only 
the modules you specify explicitly. This command, which is the default, deletes 
related modules in a manner consistent with the intent of Adas scope and 
visibility rules. The exact effect depends on module relationships. 


The distinction between related and directly related for subunits is analogous to 
that for library packages. 
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C.2.14.1 


Setting Modules for Package Bodies 

Modules for package bodies are not automatically set by the debugger. 

You may need to set the modules for library package bodies yourself so that you 

can debug the package body or debug subprograms declared in the corresponding 
package specification. F s 


C.2.15 Resolving Overloaded Names and Symbols 


When you encounter overloaded names and symbols, the debugger issues a 
message like the following: 

%DEBUG-E-NOTUNQOVR, symbol 'ADD' is overloaded 

use SHOW SYMBOL to find the unique symbol names 

If the overloaded symbol is an enumeration literal, you can use qualified 
expressions to resolve the overloadings. 

If the overloaded symbol represents a subprogram or task accept statement 
you can use the unique name generated by the compiler for the debugger The 
compiler always generates unique names for subprograms declared in library 
package specifications, because the names might later be overloaded in the 
package body Unique names are generated for task accept statements and 
subprograms declared in other places only if the task accept statements or 
subprograms are actually overloaded. 

Overloaded task accept statement names and subprogram names are 
distinguished by a suffix consisting of two underscores followed by an integer 
that uniquely identifies the given symbol. You must use the unique naming 

ovorW !? w ^ C °™ mandS t0 UniqUGly Spedfy a sub Pr°grmn whose name is 
oaded. However, if there is no ambiguity, you do not need to use the unique 
name, even though one was generated. 


C.2.16 CALL Command 


With Ada programs, you can use the CALL command reliably only with a 
su program that has been exported. An exported subprogram must be a library 
package*^ 3111 ^ ^ declared in the outermost declarative part of a library 

The CALL command does not check whether or not the subprogram can be 
exported nor does it check the parameter-passing mechanisms that you specify. 
Note that you cannot use the CALL command to modify the value of a parameter. 

A CALL command may result in a deadlock if it is entered when the Ada run-time 

The run ' time librai T routines acquire and release internal 
locks that allow the routines to operate in a tasking environment. Deadlock can 
result if a subprogram called from the CALL command requires a resource that 
has been locked by an executing run-time library routine. To avoid this situation 
in a nontasking program, enter the CALL command immediately before or after 

assured^ f xecuted ' However, this approach is not sufficient to 
be ex^cfuin/ ^ ^ W1 u ° CCUr m 3 taskin g Program, as some other task may 
run " time llbrar y routine at th e time of the call. If you must use 
the CALL command in a tasking program, you can avoid deadlock if the called 
subprogram does not do any tasking or input-output operations. 
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C.3 BASIC 

The following subtopics describe debugger support for BASIC. 

C.3.1 Operators in Language Expressions 

Supported BASIC operators in language expressions follow: 


Kind 

Symbol 

Function 

Prefix 

+ 

Unary plus 

Prefix 

— 

Unary minus (negation) 

Infix 

+ 

Addition, String concatenation 

Infix 

- 

Subtraction 

Infix 

* 

Multiplication 

Infix 

/ 

Division 

Infix 

** 

Exponentiation 

Infix 

A 

Exponentiation 

Infix 

= 

Equal to 

Infix 

<> 

Not equal to 

Infix 

>< 

Not equal to 

Infix 

> 

Greater than 

Infix 

>= 

Greater than or equal to 

Infix 

=> 

Greater than or equal to 

Infix 

< 

Less than 

Infix 

<= 

Less than or equal to 

Infix 

=< 

Less than or equal to 

Prefix 

NOT 

Bit-wise NOT 

Infix 

AND 

Bit-wise AND 

Infix 

OR 

Bit-wise OR 

Infix 

XOR 

Bit-wise exclusive OR 

Infix 

IMP 

Bit-wise implication 

Infix 

EQV 

Bit-wise equivalence 


C.3.2 Constructs in Language and Address Expressions 

Supported constructs in language and address expressions for BASIC follow 


Symbol Construct_ 

() Subscripting 

Record component selection 
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C.3.3 Data Types 

Supported BASIC data types follow: 


BASIC Data Type Operating System Data Type Name 

BYTE 

Byte Integer (B) 

WORD 

Word Integer (W) 

LONG 

Longword Integer (L) 

SINGLE 

F_Floating (F) 

DOUBLE 

D_Floating (D) 

GFLOAT 

G_Floating (G) 

HFLOAT 
(VAX specific) 

H_Floating (H) 

DECIMAL 

Packed Decimal (P) 

STRING 

ASCII Text (T) 

RFA 

(None) 

RECORD 

(None) 

Arrays 

(None) 


-r.» ^wuyymy 

If yo U make changes to a program in the BASIC environment and attempt 
to compde th e program with the /DEBUG qualifier without first saving or 

SSSF'r 1 *iT als error “ Unsaved chan ^ m 

Duggmg available. To avoid this problem, save or replace the program and 

then recompile the program with the/DEBUG qualifier. P ^ ’ 

C.3.5 Constants 

^34^GFLOm^°/ t w f<>rm ’numerie-stringltype} (such as 
in dSu^^ H f0nn "* <SUCh 88 25% f ° r ^ 25 » “• "* - W-W 

C.3.6 Evaluating Expressions 

w2r! Si T the BASIC lan « u *«e do ™t necessarily overflow 

when evaluated by the debugger. The debugger tries to compute a numericaUy 

.. re s u h, even when the BASIC rules call for overflows. This difference is 
particularly likely to affect DECIMAL computations. 

C.3.7 Line Numbers 

The sequential line numbers that you refer to in a debugging session and that are 
isplayed in a source code display are those generated by the compiler When a 

rnd? C Pr ? gram m l clud J es or a PPends code from another file, the included lines of 
code are also numbered in sequence by the compiler. nGS ° f 
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C.3.8 Stepping into Routines 

The STEP/INTO command is useful for examining external functions, owew , 
if you use this command to stop execution at an internal subroutine or a DEF the 
debugger initially steps into run-time library (RTL) routines, providing you w 
no useful information. In the following example, execution is paused at line 8, at 

a call to Print_routine: 


-> 8 GOSUB Print_routine 

9 STOP 

20 Print_routine: 

22 IF THEN P PRINT "The winning ticket is #";Winning_ticket 

23 ELSE PRINT "The game goes on." 

24 END IF 

25 RETURN 

A STEP/INTO command would cause the debugger to step into the relevant^RTL 
code and would inform you that no source lines are available for display. On the 
other hand a STEP command alone would cause the debugger to procee ire y 
to source line 9, past the call to Print_routine. To examine the source code of 
subroutines or DEF functions, set a breakpoint on the routine label (for exa p , 
enter the SET BREAK PRINT_ROUTINE command). You can then suspend 
Section exactly at the start of the routine (line 20, in this example) and then 
step directly into the code. 

C.3.9 Symbolic References 

All variable and label names within a single BASIC program must be unique. 
Otherwise the debugger cannot resolve the symbol ambiguity. 

C.3.10 Watchpoints 

In BASIC you can set a watchpoint only on variables that are ec are m 
COMMON or MAP statements (static variables). You cannot set watchpoints o 
variables explicitly declared with the DECLARE statement. 


C.4 BLISS 

The following subtopics describe debugger support for BLISS. 

C.4.1 Operators in Language Expressions 

Supported BLISS operators in language expressions follow: 


Kind 

Symbol 

Function 

Prefix 


Indirection 

Prefix 

+ 

Unary plus 

Prefix 

— 

Unary minus (negation) 

Infix 

+ 

Addition 

Infix 

- 

Subtraction 

Infix 

* 

Multiplication 

Infix 

/ 

Division 

Infix 

MOD 

Remainder 
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Kind Symbol Function - 

Infix 

A 

Left shift 

Infix 

EQL 

Equal to 

Infix 

EQLU 

Equal to 

Infix 

eqla 

Equal to 

Infix 

NEQ 

Not equal to 

Infix 

NEQU 

Not equal to 

Infix 

NEQA 

Not equal to 

Infix 

GTR 

Greater than 

Infix 

GTRU 

Greater than unsigned 

Infix 

GTRA 

Greater than unsigned 

Infix 

GEQ 

Greater than or equal to 

Infix 

GEQU 

Greater than or equal to unsigned 

Infix 

GEQA 

Greater than or equal to unsigned 

Infix 

LSS 

Less than 

Infix 

LSSU 

Less than unsigned 

Infix 

LSSA 

Less than unsigned 

Infix 

LEQ 

Less than or equal to 

Infix 

LEQU 

Less than or equal to unsigned 

Infix 

LEQA 

Less than or equal to unsigned 

Prefix 

NOT 

Bit-wise NOT 

Infix 

AND 

Bit-wise AND 

Infix 

OR 

Bit-wise OR 

Infix 

XOR 

Bit-wise exclusive OR 

Infix 

EQV 

Bit-wise equivalence 

tructs in 

Language and Address Expressions 

Supported constructs in 

language and address expressions for BLISS follow: 

oymDoi Construct ---- 

[] 

Subscripting 

[fldname] 

Field selection 

<p,s,e> 

Bit field selection 
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C.4.3 Data Types 

Supported. BLISS d&ts typos follow. 


BL ISS Data Type 

BYTE 

WORD 

LONG 

QUAD (Alpha specific) 

BYTE UNSIGNED 

WORD UNSIGNED 

LONG UNSIGNED 

QUAD UNSIGNED 
(Alpha specific) 

VECTOR 

BITVECTOR 

BLOCK 

BLOCKVECTOR 
REF VECTOR 
REF BITVECTOR 
REF BLOCK 
REF BLOCKVECTOR 


Operating Syste m Data Type Name 

Byte Integer (B) 

Word Integer (W) 

Longword Integer (L) 

Quadword (Q) 

Byte Unsigned (BU) 

Word Unsigned (WU) 

Longword Unsigned (LU) 
Quadword Unsigned (QU) 

(None) 

(None) 

(None) 

(None) 

(None) 

(None) 

(None) 

(None) 


C.5 CC 


The following subtopics describe debugger support for C. 


Supported C operators in language expressions follow: 

Kind Symbol Function__ 

Prefix 

* 

Indirection 

Prefix 

& 

Address of 

Prefix 

sizeof 

size of 

Prefix 

— 

Unary minus (negation) 

Infix 

+ 

Addition 

Infix 

- 

Subtraction 

Infix 

* 

Multiplication 

Infix 

/ 

Division 

Infix 

% 

Remainder 

Infix 

« 

Left shift 

Infix 

» 

Right shift 

Infix 

= = 

Equal to 

Infix 

! = 

Not equal to 
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Kind 

Symbol 

Function 

Infix 

> 

Greater than 

Infix 

>= 

Greater than or equal to 

Infix 

< 

Less than 

Infix 

<= 

Less than or equal to 

Prefix 

~ (tilde) 

Bit-wise NOT 

Infix 

& 

Bit-wise AND 

Infix 

1 

Bit-wise OR 

Infix 

A 

Bit-wise exclusive OR 

Prefix 

f 

Logical NOT 

Infix 

&& 

Logical AND 

Infix 

1 1 

Logical OR 


/• as the comment delimiter. The £tZT 

files t ? A k n6lther needGd n ° r rec °g nized -) To permit debugger log 

delLLr^if it T « U f geT mpUt> thG debugger sti11 ^cognizes ! as a clment 
delimiter if it is the first nonspace character on a line. comment 

in both c 

prefix - is synonymous to prefix 8 ■ ■ or 

SS£=3?3“=T 

cowman ? 6 C ° ntentS of a memory location, you must use an explicit DEPOSIT 

C.5.2 Constructs in Language and Address Expressions 

Supported constructs in language and address expressions for C follow: 


Symbol 


Construct 


[] 


(period) 


Subscripting 

Structure component selection 
Pointer dereferencing 


C-23 




















C.5.3 Data Types 


Supported C data types follow: 

C Data Type Operating System Data Type Name 

_int64 

(Alpha specific) 

Quadword Integer (Q) 

unsigned_int64 

(Alpha specific) 

Quadword Unsigned (QU) 

Longword Integer (L) 

_int32 

(Alpha specific) 


unsigned_int32 

(Alpha specific) 

Longword Unsigned (LU) 

Longword Integer (L) 

int 

unsigned int 

Longword Unsigned (LU) 

_intl6 

Word Integer (W) 

(Alpha specific) 


unsigned_intl6 

(Alpha specific) 

Word Unsigned (WU) 

short int 

Word Integer (W) 

unsigned short int 

Word Unsigned (WU) 

char 

Byte Integer (B) 

unsigned char 

Byte Unsigned (BU) 

float 

F_Floating (F) 

_f_float 

F_Floating (F) 

(Alpha specific) 


double 

D_Floating (D) 

double 

G_Floating (G) 

_g_float 

(Alpha specific) 

G_Floating (G) 

IEEE S_Floating (FS) 

float 

(Alpha specific) 

IEEE S.Floating (FS) 

_s_float 

(Alpha specific) 

IEEE T.Floating (FT) 

double 

(Alpha specific) 

IEEE T_Floating (FT) 

_t_float 

(Alpha specific) 


enum 

(None) 

struct 

(None) 

union 

(None) 

Pointer Type 

(None) 

Array Type 

(None)_____ 

Floating point numbers of type float may be represented by F_Floating or IEEE 

S Float, depending on compiler switches. 

Floating point 
D_Floating, or 

numbers of type double may be represented by IEEE T.Float, 
G_Floating, depending on compiler switches. 
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C.5.4 Case Sensitivity 

. that — apd 

C.5.5 Static and Nonstatic Variables 

ld h Ltm Wing ^ C ‘ a8SeS ^ a ‘ l0Cated StatM * s “c, globaldef, 

auttd Sr'sT are f <°» the stack 

their downing LTe “aZetn th^IT^ *“ ta “ «* »*« 

C.5.6 Scalar Variables 

- p d *r — 18 as 

™d Paragraphs Pr “'' ide addi th>nal information about char variables 

hy the debugger “a byte integers, not ASCII 
use the /ASCII qualifier: r vanabIe ch as a character, you must 

DBG> EXAMINE/ASCII ch 
SCALARS\main\ch: "A" 

:rsr^.rsrsr5»“^“ —•» 

DBG> DEPOSIT/ASCII ch = 'z' 

DBG> EXAMINE/ASCII ch 
SCALARS\main\ch: "z" 

^ EXAMINE command. 

static long li = 790374270; 
static int *ptr = sli; 


DBG> EXAMINE *ptr 
*SCALARS\main\ptr: 


790374270 


C.5.7 Arrays 


e«mte U S“^ 'TsZ ofT' .*»* can 

element, using array . 

into only one array element at a time. ' And you can de P° slt 

C.5.8 Character Strings 

fo^ n ^:* e ™ inated ASCH strings (ASCIZ 
qualifier so that the debugger can interarrf " Se . the /ASCIZ <or /AZ > 

can examine and deposit MWd“ 1 chSacLS i' the s Pr ? PPrly ' Yra 

subscripting operators (T 1) WMon r. string using the C array 

use the /ASCII qualifier. y examme and deposit individual characters, 
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Assume the following declarations and assignments: 

static char *s = "vaxie"; 

static char **t = &s; . 

The EXAMINE/AZ command displays the contents of the character strrng pointed 

to by *s and **t: 

DBG> EXAMINE/AZ *S 
*STRING\main\s: "vaxie" 

DBG> EXAMINE/AZ **t 

**STRING\main\t: "vaxie' _ 

TVlp nFPOSIT/AZ command deposits a new ASCIZ string in the variable pointed 
m by . ®^mE/AZ command displays the new contents of the stnng. 

DBG> DEPOSIT/AZ *s = "DEC C" 

DBG> EXAMINE/AZ *S, **t 

*STRING\main\s: "DEC C" 

* * STRING\main\t: ulljL u 

DBG> EXAMINE/ASCII s [3] 

[3]: " " 

DBG> DEPOSIT/ASCII S [3] = 

DBG> EXAMINE/AZ *s, **t 
*STRING\main\s: "VAX-C" 

**STRING\main\t: "VAX-C" 

and deposit data into structures one member at a time. 

lb reference members of a structure ”^^ s ^2^!you^TJ{erence 
references. That is, if variable p is a p If variable x refers to the 

member y of that structure-££^member of that 
base of the storage allocated for a structure, you cui 

structure with the x.y expression. 

The debugger «. odes to refemnce “aSd 

Un,0n ' ffslt ^ a t™*When such a reference is ambiguous-when there .s 
moSttn'onestruiwitha^ 

^h"aTtonl to^"r i a structure or union apply to both x.y 

71 „X one of the members, y, belongs in the structure or union, X, that is the 
one that is referenced. 

. If only one of the members, y, is in the same scope as x, then that is the one 
that is referenced. 

x and y. 
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C.6 

C.6.1 

C.6.2 


C_PLUS_PLUS 

The following subtopics describe debugger support for C++. 

The %name Lexical Function 

Use of the %name lexical function is required with debugger commands to 
When^sed^th ^ 5 ntl J? es m DEC C++ > such as functions and data members 
Terence Examn^r “ ^ ^ Pl&Ced between the inland and the 
where its use is required™* Sh0Wn “ the Mlowin S sections for cases 

Operators in Language Expressions 

Supported C++ operators in language expressions follow: 


Kind Symbol Function 

Prefix 

* 

Indirection 

Prefix 

& 

Address of 

Prefix 

sizeof 

size of 

Prefix 

- 

Unary minus (negation) 

Infix 

+ 

Addition 

Infix 

- 

Subtraction 

Infix 

* 

Multiplication 

Infix 

/ 

Division 

Infix 

% 

Remainder 

Infix 

« 

Left shift 

Infix 

» 

Right shift 

Infix 

= = 

Equal to 

Infix 

u 

Not equal to 

Infix 

> 

Greater than 

Infix 

>= 

Greater than or equal to 

Infix 

< 

Less than 

Infix 

<= 

Less than or equal to 

Prefix 

- (tilde) 

Bit-wise NOT 

Infix 

& 

Bit-wise AND 

Infix 

1 

Bit-wise OR 

Infix 

A 

Bit-wise exclusive OR 

Prefix 

f 

Logical NOT 

Infix 

&& 

Logical AND 

Infix 

1 1 

Logical OR 


point u ) is an operator, it cannot hp iiqpH 
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The debugger accepts the asterisk (*) prefix as an indirection operator in 

both C^fanguage expressions and pret when 

expressions, the * prefix is synonymous to the . (period) preftx P 

the language is set to C++. 

To prevent unintended modifications to the program being d> ^ other 
debugger does not support any of Uie assignment o^atorsm 

'SS&SStfi rroSn^ouutU do so with an explicit deposit 
command. 

C.6.3 Constructs In Language and Address Expressions 

Supported constructs in language and address expressions for C++ follow. 



Subscripting 

Structure component selection 
Pointer dereferencing 


C.6.4 Data Types 

Supported C++ data types follow. 


_int64 

(Alpha specific) 

unsigned_int64 

(Alpha specific) 

_int32 

(Alpha specific) 

unsigned_int32 

(Alpha specific) 

int 

unsigned int 

_intl6 

(Alpha specific) 

unsigned int 16 

(Alpha specific) 

short int 

unsigned short int 
char 

unsigned char 

float 

_ _f_float 
(Alpha specific) 

double 

double 


Operating System Data Type Name 

Quadword Integer (Q) 

Quadword Unsigned (QU) 

Longword Integer (L) 

Longword Unsigned (LU) 

Longword Integer (L) 

Longword Unsigned (LU) 

Word Integer (W) 

Word Unsigned (WU) 

Word Integer (W) 

Word Unsigned (WU) 

Byte Integer (B) 

Byte Unsigned (BU) 

F_Floating (F) 

F_Floating (F) 

D_Floating (D) 

G_Floating (G) 
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C++ Data Type 

Operating System Data Type Name 

g float 

(Alpha specific) 

G_Floating (G) 

float 

(Alpha specific) 

IEEE S_Floating (FS) 

_s_float 

(Alpha specific) 

IEEE S_Floating (FS) 

double 

(Alpha specific) 

IEEE T_Floating (FT) 

_t_float 

(Alpha specific) 

IEEE T_Floating (FT) 

enum 

(None) 

struct 

(None) 

union 

(None) 

Pointer Type 

(None) 

Array Type 

(None) 


9 pw a1 a- - -r 1 may De represented by F_Floating or IEEE 

o_I loat, depending on compiler switches. 

Fioating point numbers of type double may be represented by IEEE T_Float 
D_Floatmg, or G_Floating, depending on compiler switches. 

C.6.5 Case Sensitivity 

Symbol names are case sensitive for C++, meaning that uppercase and lowercase 
letters are treated as different characters. lowercase 

C.6.6 Qualified Class Names 

Discussions in some of the following sections use the term qualified class names 
to descnbe how to compose the names of class members when using the debugger 
If a class is not defined within another class, the qualified class name is merely ' 
the name of the class itself. However, if a class is nested within another class the 
of Mlol M 7“ ediate ‘y contaming class must precede it, separated with a pair 
and sd on * COntainlns clas8 is its name must be prefixed, 

The following are examples of properly qualified class names: 


DBG> set break %name 'C::f' 

DBG> set break %name 'F00::BAR::BAZ: :g' 


f is a member of class C 
g is a member of BAZ, 
which is nested in BAR, 
which is nested in F00 


C.6.7 Using the OpenVMS Debugger with C++ Data 

This section describes how to use the OpenVMS Debugger with C++ data. 

C.6.7.1 Nonstatic Data Members 

This section describes how to refer to data members that are not declared static. 
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C 6 7 1 1 Noninherited Data Members To refer to a nonstatic data member that 
S’ defined directly in a C ++ class (or a struct or union) use its name just as with 
a C language struct or union member. The following example shows the correct 
use of a nonstatic data member reference: 

DBG> examine x.m, p->m 

C.6.7.1.2 Inherited Data Members Currently, debugger support distinguishes 
nonstatic data members inherited from various base class by Pre&ang the 
names with a sequence of significant base class names on the nfaentance path 
to the member and then the class that the member is declared in. A base class 
on a path from an object to a member is significant if the base class l ^®^ 
derived from using multiple inheritance. Thus, a base class is significant if it 
mentioned in a base list containing more than one base specifier. 

This notation generates the minimum number of base class prefixes necessary 
to descrite the inheritance path to a base class, because it involves naming only 
those base classes where one must choose where to proceed next when traversi g 
the path. When no multiple inheritance is involved, the reference is of the 

following form: 

%name’CLASS::member’" 

To refer to nonstatic data members inherited from base classes of an object 
auote the sequence of significant qualified base class names and the member 
name (separated by double colons) with %name. Specify the sequence of sigmfican 
base classes, in the order from the object’s most derived significant class tot 
significant base class closest to the object. For example, consider the inheritance 
graph for the following declarations: 


struct A { 
struct B : 
struct C { 
struct D : 
struct E : 
struct F { 
struct G : 
struct H : 
struct I : 
struct J : 


int a_member; }; 

A { int b_member; }; 
int cjnember; }; 

B, C { int d_member; 
D { int ejnember; }; 
int f_member; ); 

F { int gjnember; }; 
E, G ( int hjnember; 
H t int ijnember; }; 
I { int jjnember; }; 


}; 


}; 


static J j_object; 

Because classes B, C, E and G are mentioned in base lists, which involve mvdtaple 
inheritance they are the significant classes that appear as prefixes. The follow g 
examples are references to all the members through debugger deposit commands. 
Note that the class of the inherited member itself appears before the member 
name regardless of whether or not the member belongs to a significant class. 

C.6.7.1.3 inherited Virtual Data Members In the OpenVMS Debugger symbolic 
access to data members of virtual base classes is currently not supported. The 

to this is that the pointer member named __bptr is present m such 

objects. 




C.6.7.2 Static Data Members 

To refer to a static data member, quote its qualified class name, two colons (::), 
and then the member name, with %name. 

The following examples show the correct use of static data member references: 

DBG> examine Iname 'C::s' 

DBG> examine %name 'F00::BAR::BAZ::sdm' 

C.6.7.3 Reference Objects and Reference Members 

To access the values of objects declared with a reference, use the name of the 
object. 

The OpenVMS Debugger treats data members declared with a reference type as 
though they were pointer variables; thus, you must use the * or -> dereference 
operators on their names. For example, consider the following code: 

class C { 
public: 

int &refjnem; 

C(int &arg) : ref_mem(arg) {} 

} r 

main() 

{ 

auto int obj = 5; 
auto int &ref_obj = obj; 
auto C c(obj); 
obj = 23; 

} 


The following sequence shows the correct way to use the debugger to examine the 
members: 

stepped on return from routine REF\main 
to REF\main\%LINE 13+16 
13: } 

DBG> examine obj, ref_obj 
REF\main\obj: 23 

REF\main\ref_obj: 23 

DBG> examine c 
REF\main\c 

refjnem: 2144211292 

DBG> symbolize c.refjnem 
address 7FCE1154: 

REF\main\c 

DBG> examine *c.refjnem 
*REF\main\c.refjnem: 23 

C.6.7.4 Pointers to Members 

Objects that are pointers to members are represented as 64-bit integers. 

C.6.7.5 Referencing Entities by Type 

To examine and display the value of an object or member by type, use the 
command examine/type. Similarly, you can modify the value of an expression 
to be deposited to a type you specify by using the command deposit/type. With 
the /type qualifier, the syntax for these commands is as follows: 

deposit/type=(name) 
examine/type=(name) 
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The type denoted by name must be the name of a variable or data type declared 
in the program. The /type qualifier is particularly useful for referencing C++ 
objects that have been declared with more than one type. 

C.6.8 Using the OpenVMS Debugger with C++ Functions 

This section describes how to reference the various kinds of functions and 
function arguments. 

C.6.8.1 Referring to Overloaded Functions 

To find the symbolic names of functions in your code, use the show symbol 
command. If the function is overloaded, use the wildcard character (*) in the 
name specification to display the overloaded symbol names. 

For example, consider the following code: 

class base 

{ 

public: 
base () ; 
base( int ); 

-base () ; 

int base_fl(); 

void base_f2 (); 
void base_f2( int ); 
void base_f2( char ) ; 

}; 

The following sequence shows how to display overloaded symbols and determine 
the appropriate function reference: 

DBG> set break %name 'base::base_f2' 

%DEBUG-E-NOTUNQOVR, symbol 'base::base_f2' is overloaded 
use SHOW SYMBOL to find the unique symbol names 
DBG> show symbol *base_f2 

overloaded symbol CXX_TlO_179\base::base_f2 

overloaded instance CXX_T10_179\base: :base_f2_l 
overloaded instance CXX_T10_179\base::base_f2_2 
overloaded instance CXX_TlO_179\base: :base_f2_3 

DBG> set break %name 'base::base_f2_2' 

DBG> step 

stepped to CXX_T10_179\main\%LINE 20 
20: x.base_f2(); 

DBG> step 

stepped to CXX_T10_179\main\%LINE 21 
21: x.base_f2(5); 

DBG> step 

break at routine CXX_T10_179\base::base_f2_2 
12: void base_f2( int ) {} 

DBG> step 

stepped to CXX_T10_179\main\%LINE 22 
22: x.base_f2('W'); 

stepped to CXX_T10_179\main\%LINE 22 

%DEBUG-I-EXITSTATUS, is 'ISYSTEM-S-NORMAL, normal successful completion' 

DBG> A Z 
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C.6.8.2 Referring to Static and Nonstatic Member Functions 

To refer to a member function, quote, with %name, its qualified class name, two 
colons (::), and the name of the member function. If the member function is 
overloaded, append the suffix_ integer-number. 

The following examples show the correct use of member function references: 

DBG> set break %name 'MYSTRING::length' 

DBG> set break %narae 'MYCOMPLEX::format_1', %name 'MYCOMPLEX::format 2' 

C.6.8.3 Referring to Constructors 

To refer to a constructor, state the name. If a constructor is overloaded, append 
the suffix_ integer-number. 

The following examples show the correct use of constructor references: 


DBG> set break F00 
DBG> set break MYSTRING_1 

C.6.8.4 Referring to Destructors 

To refer to a destructor, quote its name, including the tilde (~), with %name. 

The following example shows the correct use of a destructor reference: 

DBG> set break %name '~F00' 

C.6.8.5 Referring to Conversions 

To refer to conversion operators from a class SRC to a type dest, quote SRC two 
colons and then dest with %name. 


The set of atomic types are drawn from the following set of names: 


void char 

unsigned_short int 

unsigned_long float 


signed_char unsigned_char signed_short 
signed_int unsigned_int signed“long 
double long_double 


Pointer types are named (type) *. Reference types are named (type) & . The types 
struct, union class and enum are named by their tags and the qualifiers const 
and volatile precede their types with a space in between. For example: 

DBG> set break %name 'C::int', %name 'C::(const S)&' 


C.6.8.6 Referring to User-Defined Operators 

The following operators may be overloaded by user-defined functions: 


< 

« 
+ + 


* 

> 

» 


/ 

+ = 
»= 
->* 


«= 


-> 


& 

/ = 
I - 

i] 


%= 

<= 

o 


>= 

delete 


See §7.2 of The Annotated C++ Reference Manual (shipped with C++ 
documentation) for more details. 


i 

&— 

&& 

new 


To refer to such user-defined functions, quote the operator characters with %name 
As with regular functions, prefix the string quoted by %name with a qualified 
class name and two colons (::) if the user-defined operator is a member function. 

Similarly, if the function is overloaded, append the suffix integer jnumber to 

the operator characters. In particular, this suffix is necessary if both unary and 
binary instances of an operator such as + are defined, or if prefix instances of ++ 
or — are defined. 
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C.6.8.7 


The following examples show the correct use of user-defined function references. 


DBG> set break %name 'MYSTRING::+' 

DBG> set break %name 'COUNTER::++_!', %name 'COUNTER: :++_2 


Referring to Function Arguments 

In OpenVMS Debugger referencing, you use this, *this, and this->m as follows: 


• All nonstatic member functions have a pointer parameter available named 
this. For example: 

DBG> examine this 

• Use *this to examine the prefix object that a member function is invoked 
against. For example: 

DBG> examine *this 

• Use the this parameter to refer to a data member m of the prefix argument to 
a member function. For example: 

DBG> examine this->m 


C.7 COBOL 

The following subtopics describe debugger support for COBOL. 

C.7.1 Operators in Language Expressions 

Supported COBOL operators in language expressions follow: 


Kind 

Symbol 

Function 

Prefix 

+ 

Unary plus 

Prefix 

- 

Unary minus (negation) 

Infix 

+ 

Addition 

Infix 

- 

Subtraction 

Infix 

* 

Multiplication 

Infix 

/ 

Division 

Infix 

** 

Exponentiation (VAX specific) 

Infix 

= 

Equal to 

Infix 

NOT = 

Not equal to 

Infix 

> 

Greater than 

Infix 

NOT < 

Greater than or equal to 

Infix 

< 

Less than 

Infix 

NOT > 

Less than or equal to 

Infix 

NOT 

Logical NOT 

Infix 

AND 

Logical AND 

Infix 

OR 

Logical OR 
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C.7.2 Constructs in Language and Address Expressions 

Supported constructs in language and address expressions for COBOL follow: 

Symbol Construct -—- 

Subscripting 

Record component selection 
Record component selection 

C.7.3 Data Types 

Supported COBOL data types follow: 


() 

OF 

IN 


COBOL Data Type 


COMP 

COMP 

COMP 

COMP-1 

COMP-1 
(Alpha specific) 

COMP-2 

COMP-2 
(Alpha specific) 

COMP-3 

INDEX 

Alphanumeric 

Records 

Numeric Unsigned 
Leading Separate Sign 
Leading Overpunched Sign 
Trailing Separate Sign 
Trailing Overpunched Sign 


Operating System Data Type Name 


Longword Integer (L,LU) 

Word Integer (W,WU) 

Quadword Integer (Q,QU) 

F_Floating (F) 

IEEE S_Floating (FS) 

D_Floating (D) 

IEEE T_Floating (FT) 

Packed Decimal (P) 

Longword Integer (L) 

ASCII Text (T) 

(None) 

Numeric string, unsigned (NU) 

Numeric string, left separate sign (NL) 
Numeric string, left overpunched sign (NLO) 
Numeric string, right separate sign (NR) 
Numeric string, right overpunched sign (NRO) 


S°FP r n ‘ nU J bers f type C0MP - 1 ma r be represented by F_Floating or 
IEEE loatmg, depending on compiler switches. 

IFF^ T® IT'- mm 0 m ? ‘ yPe C ° MP ' 2 may 1x5 represented by ^Floating or 
EEE l_Floating, depending on compiler switches. 

C.7.4 Source Display 

RFP?Acrnp Ann ° e text included in a program with the COPY, COPY 

° r REPLACE statement. However, when COPY REPLACING 

f ^ REP , L ^ C , E 18 used ’ the debugger shows the original source text instead of 
the modified source text generated by the COPY REPLACING or REPLACE 
statement. 

J 1 R^PORT^ c . annot v show the original source lines associated with the code for 
with ! REPORT 10 ^ * ^ SC v the DATA SECTI0N source lines associated 

^nerates fhfreport “° ^ aSS<,dated Wi ‘ h ““ “ mpil<id «»* 
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C.8 DIBOL 

The following subtopics describe debugger support for DIBOL. 

C.8.1 Operators in Language Expressions 

Supported DIBOL operators in language expressions follow: 


Kind 

Symbol 

Function 

Prefix 

# 

Round 

Prefix 

+ 

Unary plus 

Prefix 

- 

Unary minus (negation) 

Infix 

+ 

Addition 

Infix 

- 

Subtraction 

Infix 

* 

Multiplication 

Infix 

/ 

Division 

Infix 

// 

Division with fractional result 

Infix 

.EQ. 

Equal to 

Infix 

,NE. 

Not equal to 

Infix 

.GT. 

Greater than 

Infix 

.GE. 

Greater than or equal to 

Infix 

.LT. 

Less than 

Infix 

.LE. 

Less than or equal to 

Infix 

.NOT. 

Logical NOT 

Infix 

.AND. 

Logical AND 

Infix 

.OR. 

Logical OR 

Infix 

.XOR. 

Exclusive OR 

Constructs in 

Language and Address Expressions 

Supported constructs 

in language and address expressions for DIBOL follow: 


Symbol Construct __ 

( ) Substring 

[ ] Subscripting 

(period) Record component selection 

C.8.3 Data Types 

Supported DIBOL data types follow: 

DIBOL Data Type Operating System Data Type Name 


11 

Byte Integer (B) 

12 

Word Integer (W) 

14 

Longword Integer (L) 

Pn 

Packed Decimal String (P) 
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DIBOL Data Type_Operating System Data Type Name 


Pn.m 

Packed Decimal String (P) 

Dn 

Numeric String, Zoned Sign (NZ) 

Dn.m 

Numeric String, Zoned Sign (NZ) 

An 

ASCII Text (T) 

Arrays 

(None) 

Records 

(None) 


C.9 FORTRAN 

The following subtopics describe debugger support for FORTRAN. 

C.9.1 Operators in Language Expressions 

Supported FORTRAN operators in language expressions follow: 


Kind 

Symbol 

Function 

Prefix 

+ 

Unary plus 

Prefix 

- 

Unary minus (negation) 

Infix 

+ 

Addition 

Infix 

- 

Subtraction 

Infix 

* 

Multiplication 

Infix 

/ 

Division 

Infix 

** 

Exponentiation (VAX specific) 

Infix 

// 

Concatenation 

Infix 

•EQ. 

Equal to 

Infix 

.NE. 

Not equal to 

Infix 

.GT. 

Greater than 

Infix 

.GE. 

Greater than or equal to 

Infix 

.LT. 

Less than 

Infix 

.LE. 

Less than or equal to 

Prefix 

.NOT. 

Logical NOT 

Infix 

.AND. 

Logical AND 

Infix 

.OR. 

Logical OR 

Infix 

.XOR. 

Exclusive OR 

Infix 

.EQV. 

Equivalence 

Infix 

.NEQV. 

Exclusive OR 













C.9.2 Constructs in Language and Address Expressions 

Supported constructs in language and address expressions for FORTRAN follow: 


Symbol Construct_ 

() Subscripting 

(period) Record component selection 

C.9.3 Predefined Symbols 

Supported FORTRAN predefined symbols follow: 


Symbol Description 

.TRUE. Logical True 

.FALSE. Logical False 

C.9.4 Data Types 

Supported FORTRAN data types follow: 


FORTRAN Data Type 

Operating System Data Type Name 

LOGICAL* 1 

Byte Unsigned (BU) 

LOGICAL* 2 

Word Unsigned (WU) 

LOGICAL*4 

Longword Unsigned (LU) 

LOGICAL*8 (Alpha 
specific) 

Quadword Unsigned (QU) 

BYTE 

Byte (B) 

INTEGER* 1 

Byte Integer (B) 

INTEGER*2 

Word Integer (W) 

INTEGER*4 

Longword Integer (L) 

INTEGER*8 (Alpha 
specific) 

Quadword Integer (Q) 

REAL*4 

F_Floating (F) 

REAL*4 
(Alpha specific) 

IEEE S_Floating(FS) 

REAL*8 

D_Floating (D) 

REAL*8 

G_Floating (G) 

REAL*8 
(Alpha specific) 

IEEE T_Floating (FT) 

REAL* 16 
(Alpha specific) 

H_Floating (H) 

COMPLEX*8 

F_Complex (FC) 

COMPLEX*8 
(Alpha specific) 

IEEE S_Floating (SC) 

COMPLEX* 16 

D_Complex (DC) 

COMPLEX* 16 

G_Complex (GC) 
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FORTRAN Data Type 

Operating System Data Type Name 

COMPLEX* 16 
(Alpha specific) 

IEEE T_Floating (TC) 

CHARACTER 

ASCII Text (T) 

Arrays 

(None) 

Records 

(None) 


used internally to describe 

The debugger prints the numeric values of LOGICAT vnnaKUo „ 

instead of .TRUE, or .FALSE. Normally bft<?. LoSS? 

If significant (0 is .FALSE* and 1 is .TR^,. HoweyS 

LOGIOAI v r a OW , a blta ln a LOGICAL value to be manipulated and 
CAL values can be used in integer expressions. For this reason it is 
times necessary to see the entire integer value of a LOGICAT varinhl 
expression, and that is what the debugger shows LOGICAL vanable ° r 

COMPLEX constants such as (1.0.2.0) are not supported in debugger expressions. 

FnSTSlIi!!? 1 * ¥ AL *f. and C0Mp LEX*8 may be represented by 
r_r mating or IEEE S_Floating, depending on compiler switches. 

Floating point numbers of type REAL*8 and GOIVTPT fy*ic u 
hy boating, floating, " IEEE 

C.9.5 Initialization Code 

S?D n Afr^? ebug a program that compiled with the /CHECK-UNnFRFT nw 
PARALLEL gualiher, the “NOTATMAIN”message ap"a“asTtS"" 

DBG> RUN FORMS 

TheJKWATMABP message indicates that execution is supended before the start. 

control EnteSJae GO^mmandplacSyoV^afth^stert Sf debuf!ger 

~ 

C.10 MACRO 

The following subtopics describe debugger support for MACRO-32. 

C.10.1 Operators in Language Expressions 

m particular, the debugger accepts a complete set of compa^n^B^elfn 
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operators modeled after BLISS. It also accepts the indirection operator and the 
normal arithmetic operators. 


Kind Symbol Function__ 

Prefix 

@ 

Indirection 

Prefix 


Indirection 

Prefix 

+ 

Unary plus 

Prefix 

- 

Unary minus (negation) 

Infix 

+ 

Addition 

Infix 

- 

Subtraction 

Infix 

* 

Multiplication 

Infix 

/ 

Division 

Infix 

MOD 

Remainder 

Infix 

@ 

Left shift 

Infix 

EQL 

Equal to 

Infix 

EQLU 

Equal to 

Infix 

NEQ 

Not equal to 

Infix 

NEQU 

Not equal to 

Infix 

GTR 

Greater than 

Infix 

GTRU 

Greater than unsigned 

Infix 

GEQ 

Greater than or equal to 

Infix 

GEQU 

Greater than or equal to unsigned 

Infix 

LSS 

Less than 

Infix 

LSSU 

Less than unsigned 

Infix 

LEQ 

Less than or equal to 

Infix 

LEQU 

Less than or equal to unsigned 

Prefix 

NOT 

Bit-wise NOT 

Infix 

AND 

Bit-wise AND 

Infix 

OR 

Bit-wise OR 

Infix 

XOR 

Bit-wise exclusive OR 

Infix 

EQV 

Bit-wise equivalence___ 

>nstructs in Language and Address Expressions 

Supported constructs in language and address expressions for MACRO-32 follow. 

Symbol Construct___ 


Subscripting 

Bitfield selection as in BLISS 

The DST information generated by th7MACRO-32 assembler treats a label that 
language when examining or manipulating such data. 
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source the ,abal 

LAB4: .WORD A X3F,5[2], A X3C 

The debugger treats LAB4 as an array variable For exam nle th* f„ii rt • 

command displays the value stored in each 

DBG> EXAMINE LAB4 
•MAIN.\MAIN\LAB4 


[0]: 

003F 

[1] : 

0005 

[2]: 

0005 

[3]: 

003C 


^following " 0mm f nd dis P la y s tha value stored in the fourth word (the first 
word is indexed as element “0”): v e n st 

DBG> EXAMINE LAB4[3] 

•MAIN.\MAIN\LAB4[3]: 03C 

C.10.3 Data Types 

MACRO-32 binds a data type to a label name according to the assembler 

iSZT ‘ he labC ' " niti0n ' Supp<>rted MicRO-32 dTrSivL 


MACRO-32 Directives Operating System Patal^T^-- 

.BYTE 

Byte Unsigned (BU) 

.WORD 

Word Unsigned (WU) 

LONG 

Longword Unsigned (LU) 

.SIGNED_BYTE 

Byte Integer (B) 

.SIGNED_WORD 

Word Integer (W) 

•LONG 

Longword Integer (L) 

QUAD 

Quadword Integer (Q) 

•F_FLOATING 

F_Floating (F) 

.D_FLOATING 

D_Floating (D) 

G_FLOATING 

G_Floating (G) 

•H_FLOATING 

H_Floating(H) 


(VAX specific) 

(Not applicable) 

Packed decimal (P) 


wmpiier (MiviAUnU) (Alpha Only) 

Programmers who are porting applications written in MACRO-32 to Alnh* 
systems use the MACRO-32 compiler (AMAOROl A Zu . A1 P ha 

compiled MACRO R9 V . , KO) ' A debu ggmg session for 
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C.10.4.1 Code Relocation n VAY ovstem 

One major difference is the fact that the code is compiled. On a VAX syste , 

After you have debugged your code, you can recompile without 
/NOOPTIMIZE to improve performance. 

C ' 10 ' 4 ' 2 SVmb °£S5e1“ JtSSSZE l"op2 

rrr; zs — 

do something like the following: 


or 


dbg> examine @ap 

DBG> EXAMINE 0AP+4 


DBG> EXAMINE 0AP 
DBG> EXAMINE .+4:.+20 


; to see the argument count 
; to examine the first arg 


; to see arg count 
; to see first 5 args 


On Aloha systems the arguments do not reside in a vector in memory as they 
™vlxTvsSms Furthermore, there is no AP register on Mpha systems. If 
you type EXAMINE @AP when debugging MACRO compiled code, tee ugger 
reports that AP is an undefined symbol. 

In the compiled code, the arguments can reside in some combination of: 

• Registers 

• On the stack above the routine’s stack frame 

• Tn the stack frame if the argument list was “homed” (that is, placed m the 

stack frame to resolve VAX AP references) or if there are 
calls out of the routine that would require the register arguments to be saved 

The compiler does not require that you read the generated code to locate the 
arguments. «^vides.$A^n systems, that is, the 

argument locatio >. •$ argument, $ARG2 is the second argument, 

ZTZTa ^ are defined in CALL.ENTKY and JSB.ENTRY 
directives, but not in EXCEPTION_ENTRY directives. 

r in a q Locatina Arquments Without $ARGn Symbols 

^nemn defined fori .CALL_ 

ENTRY routine is the maximum or leThSieveSstes. For a 

J U s“ C T^toe%?ncTthe arguments'are homed in the caller’s stack tome 
fdi£ compiler cannot detect the actual number, it always creates erght $ARGn 

symbols. 

In most cases, you can easily find any additional arguments, but in some cases 
you cannot. 
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C.10.4.4 Arguments That Are Easy to Locate 

You can easily find additional arguments if: 

^ n0t ^°i med ’ and ^ ARGn symbols are defined to $ARG7 
. i If the argument list is not homed, the $ARGn symbols $ARG7 and 
above always poat into the list of parameters passed as qZworfcTthe 

toGn argUmentS " ffl to < > Uadw0rds “*»*« last defined 

P' ar f-ea‘ lis ‘ has been homed, and you want to examine an argument 

, P ‘ I‘ SS l ’ an ° r e< j ual t0 ‘he maximum number detected by the compiler 
( ther by automatic detection or as specified bv MAX if 

list is homed, $ARGn symbols 

Subsequent arguments will be in longwords following the last S i, 

Fbr example, you can examine arguments beyond the eighth argument in a JSR 
me w ere e argument list must be homed in the caller), as follows: 

DBG> EX $ARG8 ; highest defined $ARGn 


DBG> EX .+4 


next arg is in next longword 


DBG> EX .+4 ; and so on 

5?^ ^ Caller “ a ‘ ^ *» —» when 

C.10.4.5 Arguments That Are Not Easy to Locate 

You cannot easily find additional arguments if: 

' =55k 3SSire's: 

h0m !s' and ,AR ?' 1 Symbois are de "” ed only as 

ESar by at ~ s*- 

argument tlmt you'want ’ 


C— 43 



p in 4 fi Debuaainq Code with Floating Point Data 

The following list provides important information about debugging compi 
MACRO-32 code with floating point data on an Alpha system. 

1 you can use the EXAMINE/FLOAT command to examine an Alpha integer 
register for a floating point value. 

Even though there it a set of registers for floating 

MACRO-32 floating point operations on, say, R7, has 
floating point register 7. 

2 When using the EXAMINE command to examine a location that was declare 

VAX data. 

Consider the following example: 

EXAMINE/G_FLOAT R4 

preserves ^the VAXformat'of^he dateYthelLTon^ords of two consecutive 

/CFLOAT to one of these registers will not give the desired results. You can 
m3y comtoe the two hSves of such a value, however. For example, 
assume you executed the following instruction: 

MOVG DATA, R6 

You could then read the G_FLOAT value which now resides in R6 and R7 
with a sequence like the following: 


OFFFFFFFF D8E640D1 


DBG> EX R6 

.MAIN.\%LINE 100\%R6: 

riDPN pv T?7 

MAIN.\%LINE 100\%R7: 00000000 2F1B24DD 

DBG> DEP R0 = 2F1B24DDD8E640D1 

D MAIN E ULINE°100\IR0: 4568.89900000000 

4, You can deposit floating point data in an Alpha integer register with the 
DEPOSIT command. The syntax is the same as 1 1 


5. H_FLOAT is unsupported. 
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C.10.4.7 Debugging Code with Packed Decimal Data 

*• 40 “ * *«*" ** was declared 

a packed dectai Z^e ^ays the value as 

2. You can deposit packed decimal data. The syntax is the same as it is on VAX. 

C.11 MACRO-64 

The following subtopics describe debugger support for MACRO- 64 . 

c. 11.1 Operators in Language Expressions 

ext)' 6XpreSSi0n / in the ^nse as high-level 
are accepted. To permit the MACRONS* 0118 3nd ° nly a limited set of operators 
time as freely as LX^lL^a^fh! TT t0 USe ex P ressi <™ at debug- 
in MACRO-B4 language expressions that ° ugg ® r aoce P ts a number of operators 
In particular, the dSer aSpts a , T “ “A™ 0 - 64 itself, 

operators modeled after BLISS It also arc * comparison and Boolean 

normal arithmetic operators ^ the md,recti °" operator and the 


Kind 

Prefix 

Prefix 

Prefix 

Prefix 

Infix 

Infix 

Infix 

Infix 

Infix 

Infix 

Infix 

Infix 

Infix 

Infix 

Infix 

Infix 

Infix 

Infix 

Infix 

Infix 

Infix 

Infix 


+ 

Unary plus 

— 

Unary minus (negation) 

+ 

Addition 

- 

Subtraction 

* 

Multiplication 

/ 

Division 

MOD 

Remainder 

@ 

Left shift 

EQL 

Equal to 

EQLU 

Equal to 

NEQ 

Not equal to 

NEQU 

Not equal to 

GTR 

Greater than 

GTRU 

Greater than unsigned 

GEQ 

Greater than or equal to 

GEQU 

Greater than or equal to unsigi 

LSS 

Less than 

LSSU 

Less than unsigned 

LEQ 

Less than or equal to 

LEQU 

Less than or equal to unsigned 
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Prefix 

Infix 

Infix 

Infix 

Infix 


NOT Bit-wise NOT 

And Bit-wise AND 

OR Bit-wise OR 

XOR Bit-wise exclusive OR 

EQV Bit-wise equivalence 





an. 3 Data ^P® S b . ndg a ^ type , abel name acc^ 

to labels VI, V2, and V3: 

.PSECT A, NOEXE 

.BYTE 5 

VI: 

V2: 

V3 : L ° NG \ u a tn VI V2 and V3 issue a SHOW SYMBOL/TYPE 

Tn confirm the type bound to VI, VZ, ana , 

Command with a V* parameter. The following display results. 

dat atomic type, longword integer, size: 4 bytes 
^atoSftipe, longword integer, size: 4 bytes 
dat atomic type, longword integer, size: 4 bytes) 
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MACRO-64 Directives 


Operating System Data Type Name 


•S_FLOATING (Alpha 

specific) 

•T_FLOATING (Alpha 

specific) 

(Not applicable) 


S_Floating (S) 
T_Floating (T) 
Packed decimal (P) 


C .12 PASCAL 

The following subtopics describe debugger support for Pascal. 

C.12.1 Operators in Language Expressions 

Supported Pascal operators in language expressions follow: 

Function 

Unary plus 

Unary minus (negation) 

Addition, concatenation 
Subtraction 
Multiplication 
Real division 
Integer division 
Modulus 
Remainder 

Exponentiation (VAX specific) 

Set membership 
Equal to 
Not equal to 
Greater than 
Greater than or equal to 
Less than 

Less than or equal to 
Logical NOT 
Logical AND 
Logical OR 

:) is not supported in language expressions. 


Infix 

+ 

Infix 

_ 

Infix 

* 

Infix 

/ 

Infix 

DIV 

Infix 

MOD 

Infix 

REM 

Infix 

** 

Infix 

IN 

Infix 

- 

Infix 

<> 

Infix 

> 

Infix 

>= 

Infix 

< 

Infix 

<= 

Prefix 

NOT 

Infix 

AND 

Infix 

OR 

The typecast operator 











C.12.2 Constructs in Language and Address Expressions 

Supported constructs in language and address expressions or asca o ow 


Subscripting 

Record component selection 
Pointer dereferencing 



A (cir¬ 
cumflex) 


C.12.3 Predefined Symbols 

Supported Pascal predefined symbols follow: 



C.12.4 Built-In Functions 

Supported Pascal built-in functions follow: 


Symbol Meaning 

SUCC Logical successor 

PRED Logical predecessor 

C.12.5 Data Types 

Supported Pascal data types follow: 


INTEGER 

INTEGER 

INTEGER 

UNSIGNED 

UNSIGNED 

UNSIGNED 

SINGLE, REAL 

REAL 

(Alpha specific) 

DOUBLE 

DOUBLE 

DOUBLE 
(Alpha specific) 

QUADRUPLE 
(VAX specific) 


Operating System Data Type Name 

Longword Integer (L) 

Word Integer (W,WU) 

Byte Integer (B,BU) 

Longword Unsigned (LU) 

Word Unsigned (WU) 

Byte Unsigned (BU) 

F_Floating (F) 

IEEE S_Floating (FS) 

D_Floating (D) 

G_Floating (G) 

IEEE T_Floating (FT) 

H_Floating (H) 
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BOOLEAN 
CHAR 
VARYING OF CHAR 
SET 
FILE 

Enumerations 
Subranges 
typed Pointers 
Arrays 
Records 
Variant records 


(None) 

ASCII Text (T) 
Varying Text (VT) 
(None) 

(None) 

(None) 

(None) 

(None) 

(None) 

(None) 

(None) 


“ SUA “ - ®ED, BLUE] 

Floating point numbers of tvne DOIJRT F me, , 

G_Floating, or IEEE T Floating Hono a- ^ represented by D_Floating, 

attributes. ~ ’ P n mg on compiler switches or source code 

C.12.6 Additional Information 

fields, aml arr^compmTents' ^ 1 ^ ate ’ and de Posit into variables, record 
circumstances: If a variable isttr? ' 0 "] 0 ' ^ ° CCUrS Under the blowing 
might not allocate the variable If the rence ln a P r °gram, the Pascal compiler 
examine it or deposit into it, you will recX in e™ mlTa^ a ” d y ° U ^ 10 

bits^T the valuTbefnglle^osheir^lame^tb^ 6 ^! 1 !!^ 61 ^ trUncates the hi &h-order 
the high-order bits with zeros if the vflue h*" ^ var ^ ab l e ? the debugger fills 
the variable. If the deposit violates the l deposited 1S smaller than 
debugger displays an informational messTg? ° aSSlgnment compatibility, the 

SweTr(within any active block); 
contained in registers their vnli located in stack storage and are 

are initialized or assigned a valu? ^ C ° nS1 undefined until the variables 
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C.12.7 Restrictions „ o 

Restrictions in debugger support for Pascal are as follows. 

You can examrne a 

« - — d: 

DBG> EXAMINE VARS.LENGTH 
DBG> EXAMINE VARS. BODY 



C 13 PLI 

The following subtopics describe debugger support for PL/I. 

C 13.1 Operators in Language Expressions 

Supported PM operators in language expressions follow. 



Kind 

Prefix 

Prefix 

Infix 

Infix 

Infix 

Infix 

Infix 

Infix 

Infix 

Infix 

Infix 

Infix 

Infix 

Infix 

Infix 

Infix 

Prefix 

Infix 

Infix 


a_ 

> 

>= 

A < 

< 

<= 

A > 

A 

& 


Function 

Unary plus 
Unary minus (negation) 
Addition 
Subtraction 
Multiplication 
Division 
Exponentiation 
Concatenation 

Equal to 
Not equal to 
Greater than 
Greater than or equal to 
Greater than or equal to 
Less than 

Less than or equal to 
Less than or equal to 
Bit-wise NOT 
Bit-wise AND 
Bit-wise OR 
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C.13.2 Constructs In Language and Address Expressions 


Supported constructs in language and address 
Subscripting 

Structure component selection 
Pointer dereferencing 

C.13.3 Data Types 

Supported PL/I data types follow: 


expressions for PL/I follow: 




(VAX specific) 

BIT 

BIT 

CHARACTER 
CHARACTER VARYING 
FILE 
Labels 
Pointers 
Arrays 
Structures 


Bit (V) 

Bit Unaligned (VU) 
ASCII Text (T) 
Varying Text (VT) 
(None) 

(None) 

(None) 

(None) 

(None) 


C.13.4 Static and Nonstatic Variables 

Variables of the following storage classes are allocated statically 
STATIC 
EXTERNAL 
GLOBALDEF 
GLOBALREF 

o^irTregisters)? f ° Il0Wmg storage classes are allocated nonstatically (on the stack 

AUTOMATIC 

BASED 

CONTROLLED 

DEFINED 

PARAMETER 
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C.13.5 Examining and Manipulating f the examine command with pl/i data 

“at a, specihc to PM. 

c.13.5.1 EXAMINE Command Examples EXAMINE command with a few selected 

The following examples show use of the EAAMiin 

PL/I data types. _. T ,, A KV 

Examine the value of a variable declared as FIXED DECIMAL , • 

dbg> examine X 
PR0G4\X: 540.02700 

2. Examine the value of a structure variable: 

dbg> examine part 

main prog\inventory_prog\part 
ITEM: "WF-1247" 

PRICE: 49.95 

IN STOCK: 24 

3. Examine the value of a pictured variable (note that the debugger displays 
value in quotation marks): 

dbg> examine q 

MAIN\Q: "666.3330" . . . 

4 ' a“et“s> tdZplay STtS in hld^"S of d^al (the 

default): 

DBG> EXAMINE/HEXADECIMAL P 

PROG4\SAMPLE.P: 0000B2A4 . , 

5 ' ^\":nditod a “ e BASEDOT'KX^thFrR its pointer: 

dbg> examine X 

PR0G\X: ^ .vi pt"R 

Examine thep^NTE^he^TpTR ifalsodated^X b"y the following hne 
"coleZS oV x hiving been declared as BASED(PTR) aa m the 
preceding example). 

ALLOCATE X SET (PTR); 


6 . 


In this case, you examine the value of X as follows. 


dbg> EXAMINE PTR->X 
PROG6\PTR->X: "A" 

r 13 5 2 Notes on Debugger Support 

Note the following points about debugger suppo f orma t s 

tVip DEPOSIT command with entry or label vana es or 
You cannot use the DEPUMi com , the EXAMINE command 

=‘d. use the EVALUATE/ ADDRESS 

Y~t use the ^?^^^^jipEF < vAUJ^literhl^ 1 hMauM thej^anMitatic 

?=TE command. 
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You cannot use the EXAMINE EVAT TTATi? „ a 

compile-time variables and procedures. Howev" EP0SIT commands with 
DEPOSIT (but not EXAMINE) with a comnile r’ y ° U USe EVALU ATE and 
constant is the source and not the destination.' ^ COnstant ’ as lon g as the 

after a value has^eOOrsri^eTtfit Iflo^ ^ ^ h ? Ve Valid contents until 
value displayed is unpredictable. ' mme ll before that point, the 

pointer’s vatae into^rthu^making^vmborh 16 f ^ ither by depositin £ another 
depositing a virtual address into / rVn b hC ^ efarence to bot h pointers, or by 
variable by using the EVALUATE/ADDRESS fin<1 VirtUal address of a 

address into the pointer.) When you examine COmmand ’ and then deposit that 
vahie in the form of the virtual aS^OS^ S*£Z2£ ? 

°f f<>rm " or in PM language 
in order to conform to PM language mte Th Tin? ° r ,‘‘ oatin ^' >oint “nstants, 
therefore 0C01 hexadecimal, noTol hexadecimalmterna 1 representation of 10 is 

can enter floating-point constants using the syntax nEn or n.nEn. 

Longword IntegerMlfis Imn'^tlmfs na', St '" mtS « h0S . e intemal representation is 
since the debugger supports the PL/I tyn"™ 3 y Slgnificant when debugging, 
Possible to enter integer Mnstdnts^v u^ThT ^ H ° Wever ’ * ia 
%BIN operators, because %HEX > %0CT ’ a * d 

BINARY. For example, the EVALUATE/HEX A a f assumed to be FIXED 

displays 00000035. ALU ATE/HEXADECIMAL 53 + %HEX 0 command 

C.14 RPG-II 

The follow subtopics describe debugger support for RPG II. 

C.14.1 Operators in Language Expressions 

is set to RPG l°L erat ° rS ^ supported m Ia nguage expressions when the language 



Function 

Unary plus 
Unary minus (negation) 
Addition 
Subtraction 
Multiplication 
Division 
Equal to 
Not equal to 
Greater than 
Greater than or equal to 
Less than 
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Infix 

Prefix 

Infix 

Infix 


NOT > Less than or equal to 

NOT Logical NOT 

AND Logical AND 

OR Logical OR _ 





C.14.4 Setting Breakpoints or Tracepoints uslng source to numbers, logic 

With RPG II C ^‘ 8 b ^Ctine labels. Debugging KPG II 

cycle labels, user-defined tag nam , nroerams in other languages, 

programs is somewhatdiffere^ breakpoints or 

and the additional topics explain where ana now y 

tracepoints. 

c.14.4.1 paragraphs describe where you can set breakpoints (or tracepoints, 

in specifications, using line numbers. 

The RPG II program cycle detortuB.line 
processed. When setting breakpoints °r tracepoi , y file or in a 

a specification are not used. 
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C. 14.4.2 Labels 


« *** -■>* 

points in the program: P ^ eakpoint or tracepomt at these 

• i.'nsnca*-. 

ffle P ° m ‘ correspond to the File Description specification forTs 

‘ $£££?££ *£?£ nnmbtTtr **“ are 1<ladad 

record definition in an toput 0^“ “™""* *» «- 

' btoa^i^oS^tost afe w ^ C ( a ‘ C , U , lati0n ^.““cation. The first 

before testing conditioning indicatora >n The"s eVe *f? lcat j° rs ’ lf used ’ and i»st 
before executing the ^ *- 

SET BREAK Une-number.statement-number 

2” ThTsET BREAK ttl tommalTenab^^l With number 
BREAK 25.2 command puts a breakpoint fust Zf tl mdicators - The SET 

executed. If a Calculation snppifir> Q f P u J St before the operation code is 
SET BREAK 25 command nuts ® atl °" has n ? conditioning indicators, the 
executed. d Puts a breakpoint just before the operation code is 

SveTnSng^rtor mber8 ° nly W “ h Calculati °" specifications that 

been built but beiirfthTrero^ ^e output buffer has 

corresponds to the record definition in an Output spScdton br6akP ° int 


Rpr < ?T n ,T, Cifya c nRPGIIlabelasa breakpoint or a traceooint Th r „ . 

RPG II labels, which corresnnnH tn onnox y . , . a irace Pomt. The following 

in addition to user-defined tags Note that thes^l'b^J 081 ' Cycle> are P rovid e d 

source code but are accessibtoLm the debu^r The lb ^ ^ 

machine code listing. gge ‘ lhe labels do appear in the 
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C.14.5 EXA « E E ~^ mand ena , les to loolc at «£ — of a variable, the 

current table entry, an array element, or the I/O bu . 

, •, H( , 11Cie array syntax as in the following example. 

• To examine an array variable, use array synu* 

sir> seejss’= 7. i ssss’i-i 

. Specifying a table name enables you to examine the entry retrieved from the 
last LOOKUP operation. 

. *, display the contents of 

Xlgtmmtdiplays the contents of the VO buffer for the input file 
INPUT: 

DBG> EXAMINE INPUT$BUF . 

. The following command displays the ASCII equivalent of the stnng STRING, 
which is 6 characters long: 

DBG> EXAMINE/ASCII:6 STRING 

. Tb examine a variable which contains the at sign (@), use »AME as follow 

DBG> EXAMINE %NAME 'ITEMS' 

. Tb examine a nonextemal indrcator, precede it with the stnng IN. For 
example: 

DBG> EXAMINE *IN56 

*IN56: "0" . 

If an indicator is set off, 0 is displayed. If an indicator is set on, is 

You cannot examine^^^'“^“^^t^^thTSc^SSTO qualifier; 
“V: U c""inTe following example which displays the 

value of U5: 

dbg> call RPG$EXT_INDS(5) 
value returned is 0 

C 14 6 DEPOSIT Command 

Note the following points when using the DEPOSIT command: 

. You can deposit a single value into an “vata^160 into dement 2 of 

as in the following example, which deposits tne vaiue 

array ARR: 

DBG> DEPOSIT ARR(2) =150 . 

. You can deposit multiple 

the /ASCII qualifier with t TNVRPG each a character 

PARTS is an array of 10 elements m p gr • d ; pos its the strings 

string of length 3. The following PARTS: 

P04, P05, and P06 into elements 4, 5, and 6, respectively, 
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DBG> DEPOSIT/ASCII PARTS (4) = "pfUPfmDnc 
DBG> EXAMINE PARTS(4-6) P ° 4P05P06 

inv\parts 


(4) 

(5) 

( 6 ) 


'P04' 

'P05' 

'P06' 


J** Shorter 

To set a nonextemal indicator on or off with the DFPOQtt 

the indicator with the string *IN Depositing IhF E P° S J T command, precede 

indicator on or off, respectively. For examnlf the ^ SetS the 

indicator 56 on: y ple ’ the following command sets 


DBG> DEPOSIT *IN56 = "1” 

C.14.7 EDIT Command 

SST 1 inVOteS the RFG 11 ^ ™ther than the DEC Language- 

C.15 SCAN 

The following subtopics describe debugger support for SCAN. 

C.15.1 Operators in Language Expressions 

Supported SCAN operators in language expressions follow: 

Function 

Unary plus 

Unary minus (negation) 

Addition 
Subtraction 
Multiplication 
Division 
Concatenation 
Equal to 
Not equal to 
Greater than 
Greater than or equal to 
Less than 

Less than or equal to 
Complement 
Intersection 
Union 

Exclusive OR 


Infix 

Infix 

Infix 

Infix 

Infix 

Infix 

Infix 

Infix 

Infix 

Infix 

Prefix 

Infix 

Infix 

Infix 


<> 


>= 


<= 

NOT 

AND 

OR 

XOR 
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C.15.3 Predefined Symbols 

Supported SCAN predefined symbols follow: 



C.15.4 Data Types 

Supported SCAN data types follow: 


SCAN Data Type 



BOOLEAN 

INTEGER 

POINTER 

FIXED STRING ( n) 

VARYING STRING ( n ) 

DYNAMIC STRING 

TREE 

TREEPTR 

record 

OVERLAY 


(None) 

Longword Integer (L) 
(None) 

TEXT with CLASS=S 
TEXT with CLASS=VS 
TEXT with CLASS=D 
(None) 

(None) 

/"XT n 1 



FILE 

TOKEN 

GROUP 

SET 


C.15.5 Names 

You can use the names 


of the following SCAN constructs in debugger commands: 


procedures 

macros 

constants 

variables 

labels 
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C.15.6 

C.15.6.1 


Controlling Execution 

macros, and labels^”'numtere.Xt^p maCroS > Syntax 


DBG> SET BREAK find_keyword 
DBG> CANCEL BREAK exit 
DBG> SET BREAK compare trees 


j break on a trigger macro 
• cancel break on label 
break on a procedure 


— - u ^luteuure 

monitoring SCtW^p°ctarc a ™tehing 0 'wh ? 0t eapeciaUv convenient for 
he following event keywords are defined for SCAN programs. 


PICTURE 
INPUT 
OUTPUT 
TRIGGER 
SYNTAX 
ERROR 


Description 

A token is built. 

An operand in a picture is being matched. 

A new line of the input stream is read. 

A new line of the output stream is written. 

A trigger macro is starting or terminating. 

A syntax macro is starting or terminating. 
T^^atching error recovery is starting or terminating. 


Use these keywords with the /EVENT qualifier of th* f«n • 

,™ p A Mfinr . quanner at the following commands: 

(SET,CANCEL,ACTIVATE,DEACTIVATE 1 K Rtv a u 
(SET,CANCEL,ACTIVATE,DEACTIVATE) TRACE 

TOKENAs ^built; 6 foUowu,g command sets a breakpoint that triggers whenever a 

DBG> SET BREAK/EVENT=TOKEN 

by the «"«- main 

iSE££* calls a SCAN » a” S other 

L e th aWe reCOgnition of 

on SET LANGUAGE) ’ P S10ns> and other constructs (see help 

2 - st;-—~n of 
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C.15.6.2 fo]iowing po . nts about SCAN watchpoints: 

. Variables declared at MODULE level are static by default. 

. Variables declared at PROCEDURE or MACRO level are automata 
(nonstatic) by default. 

. DYNAMIC STRING variables 

be the cornet storage if 

the string’s value is changed. 

C.15.7 Examining and Depositing t he following 

The following subtopics explain how to examine and dep 

SCAN variables: 

STRING 

FILL 

POINTER 

TREE 

treeptr 

record 

OVERLAY 

C.15.7.1 STRING Variables variable truncation will occur if the 

■iqfdS: 3S& * *•"" of that 

uAnviNr STRING variable, truncation will occur if the 
2&SEK "n G S“mum s,ze established by the dedaratau 

of that variable. 

, ... ... DYNAMIC STRING variable, truncation will occur it t 

SS “n the current sire of the variable. ^ 

With FIXED and DYNAMIC ^fthe variable will be 

Ub, the new string left Justihed in the vanaMe^ 

f VARYING STRING variables, the current size of t e vana 
«T;: f wm be" to the size of the deposited string. 

C - 15 - 7 ' 2 F ' LL rmWng a FILL vanaHe causes 1tta — 

dbg> EXAMINE/FLOAT x 
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C. 15.7.3 POINTER Variables 

(-» to examine the variable that is based on the^OINTOR. F “ Symbo1 
Consider these declarations and assignments: 

TYPE symnode: RECORD 

ptr: POINTER TO symnode, 

” tr: VARYING STRING! 20 ), 

END RECORD; ; ' 

DECLARE x ; symnode; 

DECLARE xptr: POINTER TO symnode; 
xptr = POINTER (x); 

x.vstr = 'prehensile'; 

The following command displays the value of the o sir component of, 

DBG> EXAMINE x.vstr 

POINTER\MAINPOINTER\X.VSTR: 'prehensile' 

The following command ^ ^ ^ ^ ^ ^ pQ 

DBG> EXAMINE xptr->.vstr 
POINTER\MAINPOINTER\XPTR->.VSTR: 'prehensile ' 

C.15.7.4 TREE and TREEPTR Variables 

eZZcT"' ‘ he “ ” f ^ n0<leS ln “ «■ ^wing syntax- 

EXAMINE tree_variable([subscript], ...) Y 

Yoii cannot deposit into a TREE variable. 

If you specify the name of a tree with the EXAMTWi? 

displays the contents of all nodes and 1^^^“^^' 

DBG> EXAMINE voters 

e Y xa U m pi n e: 8PeCify ” by Script for that node. For 

DBG> EXAMINE voters('salem') 

teired 11 teSTor ctm'S"'’*’ “ * tree by »»«“*"« «H subscripts leading to the 
DBG> EXAMINE voters('salem',ward2) 

If you examine a TREEPTR vavioKu i 

displays the address of that tree node ^ ° V ward P tr > the debugger 

pointing to as follows: ^ Y ° U examine what a TREEPTR variable is 

DBG> EXAMINE cityptr-> 

C.15.7.5 RECORD and OVERLAY Variables 

of Se Sro™ presented 8 ^ "“h ‘ he EXAMINE oommand, all components 
RECORD, specify tKSTme ™ 

The general format is as follows: 

EXAMINE recordname 

examine recor dname.componentname.componentname 
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You examine an OVERLAY to the -me 

presented; thus, if a afferent ways. 

STRING®, the four bytes will be displayed xme 

°- 16 «,«»—»-»»- 

.. 



Kind 

Prefix 

Prefix 

Infix 

Infix 

Infix 

Infix 

Infix 

Infix 

Infix 

Infix 

Infix 

Infix 

Infix 

Infix 

Infix 

Infix 

Infix 

Infix 

Infix 

Infix 

Infix 

Infix 

Prefix 

Infix 

Infix 

Infix 

Infix 


** 

& 

// 

<> 

/= 

> 

>= 

< 

<= 

EQL 

NEQ 

GTR 

GEQ 

LSS 

LEQ 

NOT 

AND 

OR 

XOR 

EQV 


Function 

Unary plus 

Unary minus (negation) 

Addition 

Subtraction 

Multiplication 

Division 

Exponentiation (VAX specific) 

Concatenation 

Concatenation 

Equal to 

Not equal to 

Not equal to 

Greater than 

Greater than or equal to 

Less than 

Less than or equal to 
Equal to 
Not equal to 
Greater than 
Greater than or equal to 
Less than 

Less than or equal to 
Logical NOT 
Logical AND 
Logical OR 
Exclusive OR 
Equivalence 
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C.16.2 Construes in Language and Address Expressions 

UNKNOWNS™* 8 langUage and address expressions for language 



C.16.4 Data Types 

When the language is set to UNKNOWN the , 

types accepted by other languages exceot unde rstands all data 

such as picture types and file types. In UNKNOWN ^Pes, 

debugger accepts most scalar OpenVMS the 

componSt^electi^^^ex^pi?? Jis 300615 ^ ^ dot ' notation for record 
in turn is a component of a record / S, a com P°nent of a record B which 
Subscripts can be attached tn Z ’ ° Can be refere nced as A.B.C. 

array then C can be referenced as SS” 1 ** 6Xample ’ if B is an 

subscript- 1 pfrenth™ F^ r ’ e^ampl^^3h?A(2?) r ° Und SqUare 

p e ’ a nd A(2,3) are equivalent. 
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EIGHTQUEENS.C 


This appendix contains the source code for i ho nmm ,„ j . 

Thes^program^are^re'sented^here 61 ^ f 

P^cedur JL^’SS^S^ aSS,S ‘ '” deretond ^ *■» 


EIGHTQUEENS.C 


“^" IGHTQUEENS C -“» p rogram ft* solves 


Example D 1 Single-Module Program EIGHTQUEENS.C 


extern void setqueen(); 
extern void removequeen() 
extern void trycol(); 
extern void print (); 
int a[8]; /* a 

int b [16]; /* b 

int c[15]; /*c 

int x[8]; 


array[1..8 
array[2 ..1 
array[-7.. 


of boolean */ 
of boolean */ 
of boolean */ 


/* Solve eight-queens problem */ 
main () 

{ 

int i; 

for (i=0; i <=7; i++) 

a[i] = 1 ; 

for (i=0; i <=15; i++) 
b[i] = 1; 

for (i=0; i <=14; i++) 

c[i] = 1; 

trycol( 0 ) ; 

} /* End main */ 


(continued on next page) 






Example D-1 (Cent.) Single-Module Program EIGHTQUEENS.C 

void trycol( j ) 
int j; 

{ 

int m; 
int safe; 
m = -1; 

while (m++ < 7) 

safe - ia [ml -1) « (bl» * 11 “ “ ,cl " ' 1 * 11 " ll 

if (safe) 

{ 

setqueen(m, j); 
x [ j ] = m + l; 

if (j < 7 > 
trycoKj + 1); 

else 
print (); 

removequeen(m, j); 

} 

} /* End trycol */ 

void setqueen(m, j) 
int m; 
int j; 

{ 

a[m] = 0; 
b[m + j] = 0? 
c[m - j + 7] = O' 

} /* End setqueen */ 

void removequeen(m, j) 
int m; 
int j; 

{ 

a[m] = 1; 
b[m + j] = 1; 

c[m-j + 7] =1; 

} /* End removequeen */ 

void print() 

( 

int k; 

for (k=0; k<=7; k++) 

printf(” %d", x[k]); 

1 printf("\n"); 

} /* End print */ 




D.2 8QUEENS.C 


8QUEENS_SUB.c[ Ex ample D-3) ' 8QUEENSC (ExampleD- 2 )and 

Example D-2 Main Module 8QUEENS.C 

extern void try col (); 

S bffij, l : “ r * f '*• •»! <* boolean V 

int c [15]; /* £ • arra! V 1 , 6 boolean V 
int x[8]; ' Y ? “ 7] of boolean */ 


main() 


/* Solve eight-queens problem */ 


int i; 

for (i=0; i <=7; i++) 
a[i] = 1 ; 

for (i=0; i <=15; i++) 
b[i] = 1; 

for (i=0; i <=14; i++) 

cfi] = 1 ; 

trycol (0) ; 

) /* P Ei3“il'n S V Ved 6ight ' queens P r °blem! \n"); 


Example D-3 Sub-Module 8QUEENS SUB.C 


extern int a [8]; 
extern int b[16]; 
extern int c[15]; 
extern void setqueenf); 
extern void removequeen (); 
extern void print(); 

int x[8]; 


void trycol( j ) 
int j; 

{ 

int m; 
int safe; 
m = -1; 

while (m++ < 7 ) 

{ 

~ l) “ ,bI " f 11 ■■ n « <=i« - J 

{ 

setqueen(m, j); 
x[j] = m + 1; 
if (j < 7) 

trycol(j + 1 ); 

else 

print (); 

removequeen(m, j); 

} 

f /* End trycol */ 


+ 7] ==1); 


(continued on next page) 


D-3 



Example D-3 (Cont.) Sub-Module 8QUEENS 

void setqueen(m, j) 
int m; 
int j; 

{ 

a[m] = 0; 
b[m + j] = 0? 
c[m - j + 71 = °' 
j /* End setqueen */ 

void removequeen(m, j) 

int m; 
int j; 

{ 

a[m] = 1; 

b[m + j] = 1; 

c[m - j + 1] = 1 - . 

} /* End removequeen */ 

void print () 

{ 

int k; 

for (k=0; k<=7; k++) 

printf(" %d", x[k]); 

} 

printf("\n"); 

\ /* End print */ 


SUB.C 





Index 


Abort function! 2-6, 5-12, 14-10 CD -47 

CD-155, CD-242 
/ABORT qualifier, CD-215 
ACTIVATE BREAK command, 7-H CD -9 

a !3^ VAT ^ TRACE command, 7-11 CD-12 
ACTIVATE WATCH command 7-13 CD -14 
/ACTIVATING qualifier, 14-13, CD-9 CD 12 

CD-221 CD ~ 37, CD ~ 54 ’ CD ~ 56 ’ C °~ 159 > 
Activation 

breakpoint, 2-5, 3-11, 7 _n 
tracepoint, 2-5, 7 - 11 , 14-13 
watchpoint, 2-5, 7-13 
/ACTIVE qualifier, 16-11, 16-24 CD-215 

%ACTIVE_TASK built-in symbol,’ 16-11 16 14 

/cAUDR built-in symbol, CD-16 
Addresses 

depositing into, 8-25 
examining, 8-13 
obtaining, 7-8, 8-12 
specifying breakpoint on, 7-7 
symbolizing, 8-13 
Address expressions 
See also Addresses 
code, 7-6, 8-19, 10-4 
compared to language expressions, 8-7 
composite, 7-7 
vector, 15-16 

current entity, 8 - 8 , 8-13, B -6 
DEPOSIT command, 8 - 3 , CD-76 
EVALUATE/ADDRESS command, 7-8 8-12 
CD -101 9 

EXAMINE command, 8 - 2 , CD-103 
EXAMINE/SOURCE command, 10-4 
logical predecessor, 8 - 8 , 8-13, B -6 
logical successor, 8 - 8 , 8-13 B -6 
SET BREAK command, 7-4 CD-158 
SET TRACE command, 7-5 CD -220 
SET WATCH command, 7-11, CD -234 
symbolic, 8-4 

SYMBOLIZE command, 8-13 CD-306 
type of, 8-4 


/AD CD E 284 qUalifier ’ 12_6, CD ~ 62 ’ CD- 101 , 

/AFTER qualifier, CD-159, CD -221 CD-234 
Aggregates 

changing value of, 3-21, CD-76 

DEPOSIT command, 8-16, 8-17, 15-6, 15-7 
CD-76 

displaying value of, 3-15, CD-103 

ex AMINE command, 8-16, 8-17, 15-6, 15-7 
CD—103 

monitoring, 3-18 

SET WATCH command, 7-13 15-3 CD 2 Sfi 
ALLOCATE command ’ 236 

/a ^hu^giug with two terminals, 13-14 
/ALL qualifier 

ACTIVATE BREAK command, CD -9 
ACTIVATE TRACE command, CD -12 
ACTIVATE WATCH command, CD -14 
CANCEL BREAK command, CD-23 
CANCEL DISPLAY command, CD-26 
CANCEL IMAGE command, CD-28 
CANCEL MODULE command, CD-30 
CANCEL TRACE command, CD -37 
CANCEL WATCH command, CD -41 
CANCEL WINDOW command, CD-42 

BREAK command, CD -54 
EACTIVATE TRACE command, CD-56 

DELETF VATE WA J CH comman d, CD-58 
DELETE command, CD-72 

DELETE/KEY command, CD -74 

EXTRACT command, CD -121 

SEARCH command, CD -149 

SET IMAGE command, CD-172 

SET MODULE command, CD-187 

SET PROCESS command, CD -193 

SET TASK command, CD-216 

SHOW DISPLAY command, CD-250 

SHOW KEY command, CD-256 

SHOW PROCESS command, CD-268 

SHOW TASK command, CD-287 

WINDOW command, CD-296 

%AP built-in symbol, 8-22, B-4 

/APPEND qualifier, CD -121 

Arguments 

program, 2 - 2 , CD-140, CD-142 
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/ARGUMENTS qualifier, 5-9, CD-140, CD-I 
Array types, 3-15, 3-18, 8-16 
vector register, 15-6 
/ASCIC qualifier, CD-76, CD-103, CD 1 
/ASCID qualifier, CD-76, CD-103, (3D-129 
/ASCII qualifier, CD- 77 , CD-104 CD 1 
ASCII string type, CD-76, CD-103, CD 
ASCII string types, 8-16.8-27 
/ASCIW qualifier, CD-77, CD ' 194 ’5? 1 
/ASCIZ qualifier, CD-77, CD-104, CD 13 
AST (asynchronous system trap) 

CALL command, CD-16 
disabling, CD-83 

displaying AST handling conditions, CD-243 
enabling, CD—97 
AST-driven programs 
debugging, 13-25 
Asterisk (*) 

multiplication operator, B-8 
/AST qualifier, 13-26, CD-17 
ASTs (asynchronous system traps), io z 
CALL command, 13-26 
Ctrl/C service routine, 5-12 
ASTs and static watchpoints, CD-237 
At sign (@) 

contents-of operator, B-8 

execute-procedure command, 12-1, ou 

SET ATSIGN command, CD-157 
SHOW ATSIGN command, CD-244 
ATTACH command, 5-12, CD-15 
Attributes 1K1 

display, 11-3, H-6, 11-9. n - 19 ’ CD - 151 ’ 
CD-276 

B___ 

Backslash (\ ) 

current value, 8-5 

global-symbol specifier, 9-10, CD 201, B 
path name delimiter, 9-8, 10-4, B 8 
/BINARY qualifier, 8-11, CD-98, CD 10 , 
CD-104, CD-130 
%BIN built-in symbol, 8-12, B-6 
Bit field operator (<p,s,e>), B-8 
/BOTTOM qualifier, CD-146 
/BRANCH qualifier, CD-9, CD-i2, CD 2 , 

CD—37, CD-54, CD-56, CD-159, CD 22 , 
CD-299 

Breakpoints 

action, 3—13, 7—9 
activating, 2—5, 3—11, 7—11, 
canceling, 3-11, 7-11, CD-23 
conditional, 3-11, 7-9 . 

customizing display of Set/Show Breakpom 
dialog box, 3-37 
deactivating, 3-11, 7-11, CD-54 
defined, 3-8, 7-4 

delayed triggering of, 7-9, CD 159 


Breakpoints (cont’d) 

displaying, 3-10, 7-5, CD-245 
DO clause, 7-9 Q 

exception, 3 - 10 , 13-19, CD-15 

in tasking (multithread) program, 16-25 

on activation (multiprocess program), 14-13 

on label, 7-6 

on routine, 3-9, 7-6 

oli source line, 3-8, 7-6 

on task event, 16-29 

on termination (image exit), 14-13 

on unaligned data, CD-163 

on vector instruction, 15-3 

predefined, tasking (multithread) program, 

16—31 - I-, 

saving when rerunning program, 2-5, 5 li 
saving with RERUN command, 5-11, OD-iu, 
CD-55, CD-140 
setting, 3-8, 7-4, CD-158 
source display at, 10—7 
WHEN clause, 7-9 
Breakpoint view, 1-10 
Breakpoint View, 3-10 
/BRIEF qualifier, CD-257, CD 268 
Built-in symbols, 6-2, B-3 
Buttons 

debugger push button view, 1-9 
customizing, 3-29 

/BYTE qualifier, CD-77, CD-104, CD-130 


/CALLABLE EDT qualifier, CD-168 

/CALLABLE_LSEDIT qualifier, CD-168 
/CALLABLE_TPU qualifier, CD-168 
CALL command, 12-11, CD-16 
and ASTs, 13-26, CD-16 
multiprocess program, 14-6 
vectorized program, 15-22 
CALL command and floating-point parameters, 

CD-18 

%CALLER_TASK built-in symbol, 16-14 
Call-frame handlers, 13-22 

Call frames 

See Call stack 

/CALL qualifier, CD-9, CO-12, 

CD-54, CD-56, CD-159, CD-221, CD-299 
/CALLS qualifier, 16-28, CD-187, CD-287 
Call stack 

See also Scope 

and instruction display, 3-23, 20 

and register display, 3 " 23 ’ 11 T 1 J,’ t ?^ 
and source display, 3-23, 11-6,_CD 20 
and symbol search, 3-23, 9 9, CD 
displaying, 3-6, 3-23, 6-7, 13-21, CD- 
CD-280 
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CANCEL ALL command, CD-21 
CANCEL BREAK command, 7-11 CD -23 

CANCEL IMACP AY C ° mmand > U ~ 12 ’ CD-26 
CAJNCEL IMAGE command, 9-13 CD -23 

ANCEL MODE command, CD-29 

ANCEL MODULE command, 9-6 CD -30 

CANCEL RADIX command, ^ ™ 30 

CANCEL SCOPE command, 9-u, ci-S 

CANCEL command ’ 10 -3. CD-34 

oajn CEL TRACE command, 7-U CD -37 

^^JCEL WATCH command, 7-13, CD -41 
ANCEL WINDOW command, 11-15, CD-42 
Case sensitivity, 13-17 

Case-specific language and DEPOSIT/TYPE 
CD—80 f 

Catchall handler, 13-22 
Circumflex ( A ), 8-8, 8-13, B-6 
/CLEAR qualifier, CD-88 
Code 

CoW 0 StmCtiOnS ’ Ad<lreSS eXpressions 

railg CD- Iimiter ’ 8_17 ’ 15_4 ’ 15-6 ’ 15 ' 7 ’ 
Command formats 
debugger, 6-1, CD-3 
Command interface 

See also Debugger commands 
debugger, 5-1 

withDECwindows Motif, 1 - 2 , 1 - 15 , 2-9 

Command line editing keys, CD-4 
Command procedures 

See also Initialization files, debugger 
debugger, 12-1 

default directory for, 12-2, CD-157, CD-244 
displaying commands in, 12-2 CD-190 
executing, 12 - 1 , CD-7 
exiting, CD-7, CD-114, CD-135 
log file as, 12-5 

passing parameters to, 12-2, CD-59 
,^~ eCreating dis P la ys with, 11-22 CD-121 
C»mZ^ D ,Uali “ ,r ' ^ fcD -« 2 . CD-142 

binding to keys, customizing, 3-37 
Command view, 1-9, 1_15 
Comments 
format, CD-4 
Compilers 

compiler generated type, 8-4 
compiling for debugging 5-5 9 __o 
/DEBUG qualifier, 5-5 9-2, 10-1 
/LIST qualifier, 10-1 
/NOOPTIMIZE qualifier, 5-5, 13 _i 


na “ 8 ' CD - 208 

debugging, 13-19 

OS” q i Ualifier ’ CD ~ 98 - CD-104 
c,uiNJNJiCr command, 14-4, 14-14 rn_ 4 <? 

N unde C r T d C r mand ’ ^ ** Subprocess of process 
under debugger control, CD-45 

Contents-of operator, 8-6, 8-19 B-8 

c c sr- c - iNTERcEpTi ° N package > 

CtrvSrt SeqUenC6 ’ 5 ~ 12 ’ 14 ~5> 14-10, CD-47 
Ctrl/W key sequence, CD-49, CD-90 
Ctrl/Y-DEBUG 

not supported for Kept Debugger, CD-50 
not supported in DECwindows Motif interface, 

Ctrl CD ke 50 SeqUenCe ’ 2 ~ 7 ’ 5 ~ 12 ’ 5 ~ U ’ 14 ~ 13 ’ 
interrupting tasks in debugger, 16-34 
^tri/Z key sequence, 5-11 CD-53 
c /i CURDISP built-in symbol, 11-24 

%CURLOC built-in symbol, 8-8, 8-13 B-6 
Current 

display, 11-3, 11 - 19 , CD-151, CD-276 
entity, 8-8, 8-13, 8-19, B-6 
image, 9-14, CD-172, CD-255 
language, 8-10, CD-175, CD-259 
location, 6-4, 10-4, 10-5, 11-6, 11-9 
radix, 8-10, CD-199, CD-272 
scope, 9-10, CD-201, CD-273 
type, 8-25, CD-228, CD-293 
value, 8-5, B-6 

CURRENT quahfier, 9-11, 11-6, 11-9, ll-H, 

%CURRENT_SCOPE_ENTRY built-in symbol, 

%CURSCROLL built-in symbol 11-24 
JCURVAL built-in symbol, bU 
Customization 

debugger, 11-12, 11-13, 11-14, 11-19 12-1 
12-4, 12-6, 12-8, 12-9 ’ ’ 

DECwindows Motif interface, 3-28 

debugger resource file, 3-33 
key bindings on keypad, 3-37 

D 

Data types " 

See Types 

/DATEJHME qualifier, CD-77, CD-104 CD 1 qn 
DBG $ DECW$DIS pL AY logical f 

z-iu, 5-15, B-l 

DBG$INIT logical name, 12-4 B-l 
DBG$INPUT logical name, 2-9, 13-14 B 1 

219,13 i 4 B-l 

(^PROCESS logical name, 5-15, 14-2, 14-10, 
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DBG$SMGSHR logical name, 11-25 

DCL foreign command, 5-8 

DEACTIVATE BREAK command, 7-11, CDJ 
DEACTIVATE TRACE command 7-11, CD 5 
DEACTIVATE WATCH command, 7-18, CD oo 
Deadlocks 

debugging, 16-32 PD-'SO 

DEBUG command, 2-7, 5-14, 14 , 

Debugger 

command interface, 5-1 . 9 

with DECwindows Motif, 1-2, 1-lo, z 

5—15 ii 1 

customizing, 3-28, 11-12, ^ ^ ’ 

12-1, 12-4, 12-6, 12-8, 12-9 
DECwindows Motif interface, 1—1 
displaying command interface on other 
terminal, 2-9, 13-13 
displaying DECwindows Motif interface on 
other workstation, 2—8 
initialization file, 12-4 
messages, 1-18,6-2 

online help, 1-17, 6-1, CD-127 
resource file, 3-32 
starting, 2-1, 2-6, 5-7, 5-1 , - . 

terminating, 2-6, 5-11 
tutorial, command interface, 6-1 
Debugger commands 

See also Command interface 
dictionary, CD-3 

disabled in DECwindows Motif, 1 1' 

format, 6-1, CD-3 

online help, 1-18, 7 „ R rn 139 

repeating, 12-9, CD-123, CD-138, CD-139, 

CD-312 

summary, 5-16 , oiikki* 

with DECwindows Motif, 1-2, 1-15, 5 15 

Debugger resource file 
customizing, 3-33 
Debugging configurations 
See also Debugger 
default, 5-15,14-10 
multiprocess, 14-2, 14-10 
/DEBUG qualifier, 5-5, 9-2, 9-4, 10- 
shareable image, 9—11 
/DEBUG qualifier and private image copies 

performance, 5—7 
Debug symbol table 
See DST 

%DEC built-in symbol, 8-i2, B-6 

/DECIMAL qualifier, 8-11, CD-98, CD 1 , 

CD-104, CD-130 
DEC Language Sensitive Editor 
See LSE 

DECLARE command, 12-2, CD-59 
DECnet 

debugging over, 2-4, 5-10 


TYI? C * +V» vo 51 <5 

See Tasking (multithread) programs 
%DECWINDOWS built-in symbol, B-b 
DECwindows Motif interface 

debugger, 1-1 R 

displaying on other workstation, 2-8 

debugging applications, 2-8 
disabled debugger commands, 1 

MONITOR command, CD-129 
/DEFAULT qualifier, CD-104, CD-13 
DEFINE command, 12-6 CD-62 
displaying default qualifiers 
setting default qualifiers for, CD-lb i 
/DEFINED qualifier, CD-284 
DEFINE/KEY command, 12-8, CD bo 
DEFINE/PROCESS_GROUP command, 14-13, 

define/translation_attr=concealed 

command, CD-208 
/DEFINITIONS qualifier, CD-104 
DELETE command, 12-6, CD-72 
DELETE/KEY command, 12-9, CD-74 
Delta/XDelta debugger and translated images, 

13-26, 14-1 

DEPOSIT command, 8-3, CD-76 
Depositing 

DEPOSIT command, 8-3, CD /o 
instruction, 8-21, 15-12 
into address, 8-25 
into register, 3-25, 8-22, 15-4 
into variable, 3-21, 8-3, 8-14 
into vector register, 15-4 
vector instruction, 15-12 
DEPOSIT/TYPE command and case-specinc 
language, CD-80 
%DESCR built-in symbol, CD-16 
Detached processes, not for DECwindows Motif 
interface, 3-37 

/DIRECTORY qualifier, CD-257 
/DIRECT qualifier, CD-285 
DISABLE AST command, 13-25, tu oo 
DISCONNECT command, CD-84 
multiprocess program, 14-9 
Display 

startup configuration, 3-29 

Display, debugger, screen mode 

See also Source displays, Instmctions Windows 

attribute, 11-3, 11-19, CD-151, CD-276 
built-in symbol, 11-23, 11-24 
canceling, 11-12, CD-26 
contracting, 11-13, CD-118 
creating, 11—13, CD—86 
current, 11—3, 11—19, CD—151 
default configuration, 11-2, 11-4 
defined, 11-2 
DO display, 11-16, 15-22 
expanding, 11—13, CD—118 
extracting, 11-22, CD-121 
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Display, debugger, screen mode (cont’d) 
hiding, 11-12, CD-88 
identifying, H- 12 , CD-250 
instruction display (INST), 11-7 n_i fi 

kind, 11-3, H_i 5 

list, 11 - 3 , H_23, CD-250 

moving, 11-12, CD -133 

output display (OUT), 11 - 7 , U_i 7 

pasteboard, 11-3, CD-91 

predefined, 11-4 

process specific, 14-15 

prompt display (PROMPT) 11-7 

register display (REG), lllio, n_ 18 15 _ 22 

removing, 11-12, CD-90 

saving, 11-22, CD-144 

scrolling, 11 - 11 , CD-146 

selecting, 11 -ig, CD -151 

showing, 11-12, CD-86 

window, 11-2, 11 - 14 , n _ 24 

Md“* C0 ' , ’” an< '' ,1_12> U - 13 ’ CD -» 6 
example, 7-9 
exiting, CD-114, CD -135 
format, CD-4 

DO command, 14-6, 14-7, CD-93 
DO display, 11-16 

J)OWN qualifier CD-118, CD-133, CD-146 
DMs (debug symbol tables) 
creating, 9-4 
shareable image, 9-13 
source line correlation, 10-1 
Dynamic mode, CD-181 
image setting, 9-13 
module setting, 9-6 
Dynamic process setting, 14-8, CD-193 
Uynamic prompt setting, 14—2 CD-I Qfi 

/DFL OAT qU rf er ’ CD “ 88 ’ CD - 193 ’ CD-268 
/D_FLOAT qualifier, CD-77, CD-104, CD-130 


E/ac button, 1-9 

E/az button, 1-9 
/ECHO qualifier, CD-66 
EDIT command, 5-4, CD -95 
Editors 

See EDIT command 

/EDIT qualifier, CD-34, CD-207 CD-278 
ENABLE AST command, 13-25, CD -97 
Environment task 
definition of, 16-7 
/ERROR qualifier, 11-20, CD-151 
EVAL button, 1-9 

EVALUATE/ADDRESS command, 7-8 7-14 
8-12, CD-101 ’ ’ 

EVALUATE command, 8-5, CD-98 


Evaluating 

%CURVAL built-in symbol, 8-5, CD-99 B-6 
expression, 8-3, 8-5, CD-98 
memory address, 8-12, CD-101 
task, 16-13 

Event facility, 7-10, 16-29, CD-170, CD-253 
-Eventpoints 

/EVENT qualifier, 7-10, 16-29, 16-30 CD-9 
CD-12, CD-23, CD-37, Cd1 5 4, CD-56 
CD-159, CD-221 
Events 

breakpoint or tracepoint on, 7-10 

/FYAPr ng ( 7 aItithread) program, 16-29 
/EXACT qualifier, CD-34, CD-207 

EXAMINE command, 8-2 CD-103 

EXAMINE/DEFINITIONS command 13-19 

EXAMINMNSTRUG^cn command; 8 _ 19 n _g 

EXAMINE/OPERANDS command 8-19 15 _q 
XAMINE/SOURCE command, 10-4 ll_6 
Examining ’ 

address, 8-25 

EXAMINE command, 8-2, CD-103 
instruction, 8-19, I 5 _g 
register, 3-25, 8-22, 15-4 
task, 16-13, 16-28 
using vector mask, 15-13 
variable, 3-15, 8-2, 8-14 
vector address expression, 15-16 
vector instruction, 15 -g 
vector register, 15-4 
EX button, 1-g, 3 _i 5 

Exception, causing resource exhaustion or stack 
corruption, 13-19 
Exception breakpoint or tracepoint 
activating, CD-9, CD-12 
canceling, CD-23, CD-37 
deactivating, CD-54, CD-56 
setting, CD-160, CD-221 
Exception breakpoints and tracepoints 
See also Vector exceptions 
Exception breakpoints or tracepoints 
canceling, 13-20 
qualifying, 13-24, B-10 
resuming execution at, 13-20 
setting, 3-10, 13-20 
Exception handlers 
debugging, 13-19 

/EXCEPTION qualifier, 13-19, CD-9 CD 12 

Exclamation point (!) 

comment delimiter, CD-4 
Exclamation point (!) 
log file, 12-5 
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%EXC_FACILITY built-in symbol 13-24 B 

%EXC_NAME built-in symbol 13-24, B W 
%EXC_NUMBER built-in symbol ^4-M 
%EXC_SEVERITY built-in symbol, 13-24, B iu 

Execution 

interrupting 

with Ctrl/C, 5—12 
with Ctrl/Y, 2-7, 5-14, 14-13 
with Stop button, 2-6 

monitoring , c 7 

with SHOW CALLS command, 6-7, 

CD-247 

with tracepoint, 7-5, CD-220 
multiprocess program, 14-6, 00 1 1, 
resuming after exception break, 13-2U 

starting or resuming 

with CALL command, 12-11, lo 
CD-16 

with Go button, 3-6 

with GO command, 6-6, CD-125 

with S/call button, 3-8 

with S/in button, 3-8 

with S/ret button, 3—8 

with STEP button, 3-7 

with STEP command, 7-2, CD-2ay 

suspending ms 

with breakpoint, 3-8, 7-4, CD 158 
with exception breakpoint, 3-10, 13-2U, 
CD-160 

with watchpoint, 3—20, 7—11, 14— , 

CD-234 

vectorized program, 15-2 
EXIT command, 5-11, CD-114 
debugging exit handler, 13-25 
multiprocess program, 14-10 
Exit handlers 

debugging, 13-25, CD-114 
executing, 5-11, CD-114 
execution sequence of, 13-25 
identifying, 13-25, CD-254 
Exiting 

debugger, 2—6, 5—11 
EXITLOOP command, 12-10, CD-117 
/EXIT qualifier, CD-95 
$EXIT system service, 13-25 
EXPAND command, 11-13, CD-118 

Expressions 

See Address expressions, Languageexpressions 
/EXTENDED_FLOAT qualifier, CD-77, CD-105, 
CD_130 

EXTRACT command, 11-22, CD 121 


Files T 

See Command procedures, Log hies, 
Initialization files, Source files 
Final handler, 13-22 
/FLOAT qualifier, CD-77, CD 105 
/FMASK qualifier, 15-13, CD-108 

Fonts . . q 07 

for displayed text, customizing, 3-d I 

FOR command, 12-10, CD-123 
Foreign command, 5-8, 5-9 
Foreign commands, 2-2, CD-142 
Fortran I/O operations, 13-18 

Fortran RTL routines and stepping, 13 i» 

%FP built-in symbol, 8-22, B-4 
/FPCR qualifier, CD-105 
/FULL qualifier, CD-268, CD-287 
/F_FLOAT qualifier, CD-130 


General registers 
See also Registers 
/GENERATE qualifier, CD-88 
Global section watchpoints, 14-16 
Global symbols 
See Symbols 
Global symbol tables 
See GSTs 

Go button, 1-9, 3-6 
GO command, 6—6, CD—125 
multiprocess program, 14-6 
GSTs (global symbol tables) 
creating, 9—4 
shareable image, 9-12 
/G_FLOAT qualifier, CD-78, CD-105, CD 


H 


Handlers, 13—22 

Heap Analyzer, 4-1 to 4-26 

Heap Analyzer and private image copies 

tjgZSSm**. CD-140, CD-142 

online, debugger, 1-17, 6-1, CD-127 
HELP command, 6-1, CD-127 
/HEXADECIMAL qualifier, 8-11, ou-ye, 
CD-101, CD-105, CD-130 
%HEX built-in symbol, 8-12, B-6 
/HIDE qualifier, CD- 88 

/HOLD qualifier, 14-3, 14-7 ’ 10-10 ’ 10 ;f’ 7 
16-24, CD-193, CD-216, CD-268, CD-287 
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Hyphen (-) 

line-continuation character, CD-4 
subtraction operator, B-8 
/H.FLOAT qualifier, CD-78, CD-105, CD-130 

I 

/IDENTIFIER qualifier, 10-6, CD-149 

Identifiers 

search string, 10-6 
IF command, 12-10, CD-128 
/IF_STATE qualifier, 12-9, CD-66 
Images 

See also Shareable images 
privileged, securing, 9-5 
shareable, debugging, 9-11 
Indirection operator 

See Contents-of operator 
Initialization 

debugging session, 2-4, 5-7, 13-15 
Initialization code, 2—4, 13—18 * 

Initialization files 

See also Command procedures, debugger 
debugger, 12-4, B-l 
Input 

debugger, DBG$DECW$DISPLAY, 2-8 B-l 
debugger, DBG$INPUT 2-9 13 14 r\ 

/ mpuT,„, Mer , n-20/cL^:^ 

/INSTRUCTION qualifier, 11-9 11-20 
° n ^™7 ATE BREAK command, CD-9 
° n TRACE command, CD-12 

° n ^^ NCEL BREAK command, CD-23 
on CANCEL TRACE command, CD-37 

° n ^l WATE BREAK command, CD-54 

°"DEpS ATETRA , CECOran, » nd: <®-56 

on LUiFOSIT command, CD-78 

on EXAMINE command, CD-105 

on MONITOR command, CD-131 

on SELECT command, CD-152 

on SET BREAK command, CD-160 

on SET TRACE command, CD-222 
on STEP command, CD-299 
Instructions 

See also Vector instructions 
depositing, 8-19, 8-21 
display, 3-26, 8-19, 11-7, 14-15 

for routine on call stack, 3—23 11—Q 
CD-201 ’ 

display kind, 11-16 

EXAMINE/INSTRUCTION command, 8-19 
11-8, 11-9 ’ 

EXAMINE/OPERANDS command 8-19 
examining, 8-19, 11-7 
operand, 8-19, CD-106, CD-183 
optimized code, 3-26, 11-7, 13-1 


Instructions (cont’d) 

SET CD C 2of /CURRENTC ° mmand ’ n - 9 ’ 

window, 3-26 
Instruction view, 1—10 
%INST_SCOPE, 11-8 
Integer types, 3-15, 8-15, 8-25, 8-27 
Interfaces 

dec ”“- *-*- 

screen mode, 11-25 
Interrupt 

program execution, CD-43 
Interruption 

command execution, 2-6, 5-12, CD-47 

debugging session, 5-12 

program execution, 2-6, 2-7, 5-12, 5-14, 14-6 

/INTO of /'fi 14 ~ni CD ~ 47, CD “ 50 ’ C °-182 
CD-299 ’ °’ CD ~ 222 ’ CD ~ 234 ’ 

Invoking debugger, 2-6, 5-7, 14-2 14-13 
Invoking kept debugger, 2-1 


/JSB qualifier, 7-9, CD-161, CD-222, CD-300 


K 


Kept debugger 

starting, 2-1 
Kept Debugger, 1-4 

Kept Debugger and SPAWN/NOWAIT, CD-298 
Key bindings 

customizing, 3-37 
Key definitions 

creating, 12-8, CD-65 
debugger predefined, 6-2, 14-16 A-l 
deleting, 12-9, CD-74 
displaying, 12-8, CD-256 
Keypad^ mode, 12-8, CD-65, CD-182, CD-256, 

Key state, 12-8, CD-65, CD-256, A-l 


'/(LABEL built-in symbol, 7-6, B-7 

Language expressions 

t0 address expressions, 8-7 
DEPOSIT command, 8-3, CD-76 
EVALUATE command, 8-5, CD-98 
evaluating, 8-5 
FOR command, 12-10, CD-123 
IF command, 12-10, CD-128 
MONITOR command, CD—129 

WHEnIT”^ 12 - 1 *™-138,CD- 1 3 9 

WHILE command, 12-10, CD-312 
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Languages ^ ir7C 

current, 8—10, CD—175 
identifying, CD-259 
multilanguage program, 13-io 
setting, 8-10, CD-175 
support by debugger, 1-2, b-2 
Last-chance handler, 13-22 

/LATEST qualifier, CD-34, CD 207 
LAT terminals 

debugging using two 13-14 
/LEFT qualifier, CD-118, CD 133, C 

Lexical functions 

See Built-in symbol 

LIB$INITIALIZE logical name, 13-18 
%LINE built-in symbol, B-8 
EXAMINE command, 8-19 
EXAMINE/SOURCE command, 10-4 
GO command, CD-125 
SET BREAK command, 7-6 
SET TRACE command, 7-6 
STEP command, 7-2 
Line mode, CD—183 
Line numbers 

See also %LINE built-in symbol 
displaying or hiding at startup, 3 29 
in source display, 3-1, 10-1, 10 3, 10 
traceback information, 6-7, 9-3 
treated as symbol, 9-9 „ n9 o 

/LINE qualifier, 7-9, CD-9, CD 12, , 

CD-37, CD-54, CD-56, CD-105, CD-161, 

CD-223 

LINK command, 5-5, 9-4, 10-1 
shareable image, 9—11 

/LIST qualifier 10-1 CD _ 72 , CD-285 

/LOCAL qualifier, 12-6, tu ot, c. 

Local symbols 
See Symbols 

/LOCK_STATE qualifier, CD-66 
Log files 

as command procedure, 12— 
debugger, 12—5, CD—190 

name of, 12-5, CD-177, CD-260 

Logical names 

debugger, 6-2, B-l _ „ 

Logical predecessor, 8-8, 8-13, 8 19, 

Logical successor, 8-8, 8-13, 8 19, B 
/LOG qualifier, CD-66, CD-75 rn-131 

/LONGWORD qualifier, C ^“ 7 ®’ C p n _ in ’ fi 
/LONG_FLOAT qualifier, CD-78, CD 106 
/LONG_LONG_FLOAT qualifier, CD-78, CD iut> 

LSE, 5-4, CD-95 


M 


Main window, 1-5 

“3“^ display. 10-8, CM78, CD-261 
/MARK_CHANGE qualifier, CD-88 

^EXAMINE/FMASK command, 15-13 

EXAMINEATMASK command, 15-13 

masked vector operation, 15-5, 15 9. 1& 
register, VMR, 15-5, 15-9, 15-13 
Memory resources, 13-19 
Memory use 

Heap Analyzer, 4-1 
Messages 

debugger, 1-18, 6-2, CD 5 

MicroVAX 

See Workstations 

M °CANCEL MODE command, CD-29 

SET MODE [NOIDYNAMIC command, 9-b, 
9-13, CD-181 

SET MODE [NO]G_FLOAT command, CD-181 
SET MODE [NOIINTERRUPT command, 

14-6, CD-182 

SET MODE [NOIKEYPAD command, 12-8, 

CD-I 82 , i«i 

SET MODE [NOILINE command, CD-183 

SET MODE [NOIOPERANDS command, 8-19, 

CD-183 . „ , 

SET MODE [NOISCREEN command, U-i, 

SETMODE [NOISCROLL command, CD-184 
SET MODE [NOISEPARATE command, 2-9, 

13-13, CD-185 , o i q 

SET MODE [NO]SYMBOLIC command, 8-13, 

CD-185 

SHOW MODE, CD-262 
/MODIFY qualifier, CD-161, CD 223 ? 

/MODULE qualifier, CD-34, CD 2 , 

Modules, 3-2, 5-5 

See also Shareable images 
canceling, 9-6, CD-30 
information about, 9-6, CD-263 
setting, 9-5, CD-187 
traceback information, 9-3 
MON button, 1-9, 3-18 
MONITOR command, CD-129 
Monitor view, 1-10, 1Q o 

MOVE command, 11-12, CD 133 
Multilanguage programs 
debugging, 13-15 
Multiprocess programs 

CALL command, CD-16 rn_43 

CONNECT command, 14-4, 14-14, CD-48 

controlling execution, 14-6 

DBG$PROCESS logical name, 14-10 
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Multiprocess programs (cont’d) 
debugging, 14-1 

DEF cS R ° CESS - GROUPcommand ’ 14 ~ 13 > 
DISCONNECT command, 14-9, CD -84 
DO command, 14-5, CD -93 
EXIT command, 14-10, CD -114 
global section watchpoint, 14—16 
GO command, 14-6, CD-125 
process built-in symbols, 14-12 
prompt, process-specific, 14 - 2 , 1 4 8 
QUIT command, 14-10, CD -135 
screen mode features, 14—15 
SET MODE [NOJINTERRUPT command 
14-7, CD-182 

SET PRoSS S C ° mmand ’ 14 ~ 7 ’ M- 8 , CD-192 
oiiiT PROMPT command, 14-2 

SHOW PROCESS command, 14 - 3 , CD-267 
specifying processes, 14-12 
STEP command, 14-6, CD-299 
system requirements, 14-17 
Multithread programs 

See Tasking (multithread) programs 

N 

%NAME built-in symbol, B-5 

Networks 

debugging over, 2-4, 5-10 
%NEXTDISP built-in symbol, 11-24 
%NEXTINST built-in symbol, 11-24 
Next location 

See Logical successor 

%NEXTLOC built-in symbol, 8-8 8-13 B fi 

ANfcXr qualifier, 10-6, CD-149 
%NEXTSCROLL built-in symbol 11—24 
%NEXTSOURCE built-in Cbd 11-24 

SK b^ *£* ^ B-ll 

N.&a 1_1ASK built-in symbol, 16-14 
Nonstatic variables, 3-22 7-14 8-1 
/NOOPTIMIZE qualifier, 5 - 5 , I 3 _i 
NOP instruction, 8-22 
Null frame procedures and SHOW CALT S 
CD-247, CD-248, CD-281 


Object modules, 5-5, 10-1 ~ - 

^CD-l^r 1 ^’ 8 ' n ’ CD ' 98 ’ CD ~ 101 ’ CD - 106 ’ 

%OCT bSfi D qUali J e f’ CD ~ 78 - GD-106, CD-131 
/oUCl built-in symbol, 8 - 12 , B -6 

OpenVlVIS Alpha System-Code Debugger 

CONNECT command, CD -43 

REBOOT command, CD-138 


Operands 

instruction, 8-19, CD-106, CD-183 
vector instruction, 15-5 15-9 
/op E^NDS qualifier, 8-19, 15-9, CD-106, 

Operating system debugging 
CONNECT command, CD-43 
Operators (mathematical) 
address expression, B-7 
Optimization 

effect on debugging, 5-5 ii _7 iq 
/OPTIMIZE nualffer si i "l 
/OPTIONS qualifier, 9-11 

/ORIGINAL qualifier, CD -34 CD-207 
Output 

configuration, displaying, 12 - 2 , 12-6, CD-266 
configuration, setting, 12-2, 12-6, CD-190 
debugger, DBG$DECW$DISPLAY, 2-8 B-l 
debugger, DBG$OUTPUT, 2-9 13-14 r_i 
display (OUT), 11-7 ’ 

display kind, 11-17 

/OU CD-297 UaIifier ’ n ~ 2 °’ CD ~ 152 ’ CD ~ 199 ’ 

/OV CD-3 0 a 0 CD ~ 161 ’ CD_223 ’ CD " 235 ’ 
/OVERRIDE qualifier, 8-26, CD-32 CD-40 
CD-199, CD-230, CD-272, CD-293 


/PACKED qualifier, CD-78, CD-106 

%PAGE built-in symbol, 11-23 
/PAGE qualifier, 11-22, CD-218 
Parameters 

debugger command procedure 12—2 CD 
%PARCNT built-in symbol, 12-2, B-5 
Pasteboard, 11-3 
Path names 

abbreviating, 9-9 
numeric, 9-9 
relation to symbol, 9-8 
syntax, 9-8 

to specify scope, 3-23, 7-7, 9-7, 9-8 
PC (program counter) 

SHOW CALLS display, CD-247 
%PC built-in symbol 
See PC 

PCs (program counters) 

built-in symbol (%PC), 8-22 B-4 
content of, 6-5, 8-19 

EXAMINE/INSTRUCTION command, 11 — 9 , 

EXAMINE/OPERANDS command, 8-19 15-9 
XAMINE/SOURCE command, 10-4 11-6 
11-18, 11-21 ’ ’ 
examining, 8-19, 15-9 
scope, 3-23, 9-7 
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PCs (program counters) (cont’d) 

SHOW CALLS display, 6-7 

contents-of operator, 8-6, 8-19, B-8 
current entity, 8-8, 8-13, B-6 
Pointer types, 3-20,8-18 
/POP qualifier, CD-89, CD-197 

Predecessor 

See Logical predecessor 
/PREDEFINED qualifier 

on ACTIVATE BREAK command, CD-10 
on ACTIVATE TRACE command, DD-12 

on CANCEL ALL command, CD-21 

on CANCEL BREAK command, CD-25 
on CANCEL TRACE command, CD-5 i 
on DEACTIVATE BREAK command, CD-54 
on DEACTIVATE TRACE command, CD-5 1 
on SHOW BREAK command, CD-245 
on SHOW TRACE command, CD-291 

Previous location 

See Logical predecessor 

%PREVIOUS_PROCESS built-in symbol, 14-12 
%PREVIOUS_SCOPE_ENTRY built-in symbol, 

B—11 

%PREVIOUS_TASK built-in symbol 16-15 
%PREVLOC built-in symbol, 8 -8, 8-15, » ° 
Primary handler, 13-22 on 

Priority of task or thread, 3-27, 16 , 

/PRIORITY qualifier, CD-216, CD-28 
Privileges 

allocate terminal, 13-14 
Process , nn A-i 

connecting debugger to, CD-45 

disconnecting debugger from, CD-84 
releasing from debugger control, CD-84 

activation tracepoint, predefined, 14 
connecting debugger to, 14-4, 14-1 
multiprocess debugging, 14-1 

termination tracepoint, predefined, ^ 
/PROCESS qualifier, 14-6, 14-15, CD 89, 
/PROCESS_GROUP qualifier, 14-13. <^ ™ 
%PROCESS_NAME built-in symbol, 14-12 
%PROCESS_NUMBER built-in symbol, 14-12 
%PROCESS_PID built-in symbol, 14-12 
Program counter 
See PC 

/PROGRAM qualifier, 11-20, CD-152 

Pr °argument, 2-2, CD-140, CD-142 
bringing under debugger control, 2 
bringing under kept debugger control, 
display kind, 11-19 

rerunning under debugger control, 2-5 
termination, 2-5, 5-10 


2-1 


/PROMPT qualifier, 11-20, CD 152 
Prompts 

See also Command interface 

debugger, 1-15, 5-7, 5-8, 5-15, 14-2, 14-8, 
CD-196 

display (PROMPT), 11-7 
multiprocess program, 14-2, 14-0 

Protection u 

debugging with two terminals, 15-14 

of terminal, 13-14 
%PSL built-in symbol, 8-22, B-4 
/PSL qualifier, CD-107 
PSLs (processor status longwords), 8-24 
/PS qualifier, CD-107 
/PSW qualifier, CD-107 
Push button view 

customizing buttons on, 3-29 
/PUSH qualifier, CD-90 

Q___— 

/QUADWORD qualifier, 15-6, 15-7, CD 78, 

CD-107, CD-131 
QUIT command, 5-11, CD-135 
multiprocess program, 14-10 
Quotas, 13-19 
Quotation mark (”) 

ASCII string delimiter, 8-16 
instruction delimiter, 8—21 


Radix 

canceling, CD—32 
current, CD—199 
displaying, CD-272 
specifying, CD—199 
Radixes 

conversion, 8—10, B—6 
current, 8-10 

multilanguage program, lci-ib 
specifying, 8-10 
Range 

colon (:), CD-103 

“So, 8-17,15-4,15-6,15-7 
Real types, 8-15 
REBOOT command, CD-138 
Record types, 3-18,8-17 
%REF built-in symbol, CD-lb 
%REF builtin_symbol, CD-16 
/REFRESH qualifier, CD-90 
Registers 

See also Vector registers 
built-in symbols, 8-22, B-4 
depositing into, 3-25, 8-22 
display, 3-25, 11-10 
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Registers 

display (cont’d) 

for routine on call stack, 3-23 11-11 

CD-201 

display kind, 11-18 
examining, 3-25, 8-22 
PC 

See PC 
PSL, 8-24 

SET SCOPE/CURRENT command 11-11 
CD-201 ’ 

symbolizing, 8-13, CD-306 
symbols, 8-22, B-4 
variable, 3-22, 7-14, 8-1 
view, 3-25 
watchpoint, 7-14 
Register view, 1-10 
Register View, 3-25 

qU * 1 l fier ’ CD - 30 > CD-187, CD-263 
/KEMOVE qualifier, CD-90, CD-131 

REPEAT command, 12-10, CD-139 
RERUN command, 5-11,5-13,5-14 7-ii 7 r 
CD-140 ’ ’ ' 11 

passing arguments, 5-8 
Rerunning programs 

under debugger control, 2-5, 5-U 
Resource file, debugger 
customizing, 3-32 
/RESTORE qualifier, CD-216 
Return key 

logical successor, 8-8, 8-13, B-6 

^frWT N q rf fier ’ CD ~ 162 ’ CD -223, CD-300 
/RIGHT qualifier, CD-119, CD-133, CD-147 
Rooted-directory logical names 
concealed, CD-208 
Routines 

breakpoint on, 3-9, 7-6 
calling, 12-11, 15-22, CD-16 
call stack, CD-201, CD-247 
call stack sequence, 3-6, 6-7 

displaying instructions for, on call stack, 3-23, 
11 9, CD—201 

displaying register values for, on call stack 
3-23, 11-11, CD-201 

displaying source code for, on call stack 3-23 

11-6, CD-201 

EXAMINE/SOURCE command, 10-4 
multiple invocations of, 9-10, CD-201 
returning from, 3-8, 7-3 
SET BREAK command, 7—6 
SET SCOPE command, 9-11 CD-201 
SET TRACE command, 7-6 
SHOW CALLS command, 6-7 
STEP/INTO command, 7-3 
stepping into, 3-7, 7-3 
STEP/RETURN command, 7-3 
traceback information, 9-3 
tracepoint on, 7-6 


RST (run-time symbol table) 

deleting symbol records in, CD-30 
displaying modules in, CD-263 
displaying symbols in, CD-284 
inserting symbol records in, CD-187 
RSTs (run-time symbol tables), 9-5 
and symbol search, 9-7 
deleting symbol records in, 9-6 
displaying modules in, 9-6 
displaying symbols in, 9-8 
inserting symbol records in, 9—6 
shareable image, 9-13 
RUN command 
See also Execution 

DCL command, 2-1, 2-7, 5-6, 5-7, 5-13, 9-4 
debugger command, 5-7, 5-11, 5-13 5-14 
9-13, CD-142 ’ ’ 

passing arguments, 5-8 
Running programs 

under debugger control, 2-6 
under kept debugger control, 2-1 
Run-time symbol tables 
See RSTs 


s 


SAVE command, 11-22, CD-144 

/SAVE qualifier, CD-140 
/SAVE_VECTOR_STATE qualifier, 
Saving breakpoints, 2-5, 5-U 
Scalar types, 8-15 
S/call button, 3-8 
Scope 


15-22, CD-17 


built-in symbol, 11-6, 11-8, B-ll 
canceling, 9-11, CD-33 
current, 3-23, 9-10, CD-201 
default, 9-7, CD-33, CD-202, CD-273 
displaying, 9-11, CD-273 
for instruction display, 3-23, 11-9, CD-201 
tor register display, 3-23, 11-11, CD-201 
for source display, 3-23, 11-6, CD-201 
for symbol search, 3-23, 7-7, 9-7 9_io 
CD-33, CD-201, CD-273 
PC, 3-23, 9-7 

relation to call stack, 3-23, 9-9, 9-10 9-11 
11-6, 11-9, 11-U, CD-201 
SEARCH command, 10-6, CD-148 
search list, 9-7, 9-10, CD-33, CD-201 
CD-273 


SET SCOPE command, 9-10 11-6 11-9 
11-11, CD-201 ’ ’ 

setting, 3-23, 9-10, CD-201 
specifying with path name, 9-8 
TYPE command, 10-4, CD-310 
vector register, 15-1 
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Scopes 

search list, 3—23 
Screen displays 

See Displays, debugger, screen mode 

Screen management . Q o 

debugging DECwindows Motif application, 2 8 
debugging screen-oriented program, 2-9, Id id 

Screen mode, 11-1, CD-184 
built-in symbol, 11-23, 11-24 
multiprocess program, 14-15 
predefined windows, 11-24 
Screen-oriented programs 

debugging, 2-8, 2-9, 13-13 
Screen sizes 

displaying, 11-23, CD-290 
%PAGE, % WIDTH symbols, 11-23 
setting, 11 - 22 , CD-218 
/SCREEN_LAYOUT qualifier, CD-121 
SCROLL command, 11-11. CD-146 
Scroll mode, CD-184 
/SCROLL qualifier, 11-20, CD-152 

SEARCH command, 10 -5, CD - 148 rD _ 27 5 

displaying default qualifiers for lO-YCD 275 
setting default qualifiers for, 10-6, CD-205 

Sea sco h p e 1St 3-23, 9-7, 9-10, CD-201, CD-273 
source file, 10-2, CD-34, CD-207, CD-278 

Security 

image, 9-5 
terminal, 13-14 

SELECT command, 11-19, CD-151 
Semantic events, 13-5 
/SEMANTIC_EVENT qualifier, CD-dOU 
Semicolon (;) 

command separator, CD-4 

SET ABORT_KEY command, 5-12, tu ioo 
SET ATSIGN command, 12-2, CD-157 
SET BREAK command, 7—4, 10-7, Id , > 

16-25, 16-29, CD-158 

SET BREAK/UN ALIGNED JDATA command and 
system service routine, CD-164 
SET DEFINE command, 12-6, CD-167 
SET EDITOR command, 5-4, CD-168 
SET EVENT_FACILITY command, 16-30, 

CD-170 

SET IMAGE command, 9-14, CD-172 
effect on symbol definitions, CD—63 
SET KEY command, 12-9, CD-174 
SET LANGUAGE command, 8-10, CD-175 
SET LOG command, 12-5, CD-177 
SET MARGINS command, 10-8, CD-I /» 

SET MODE command, CD-181 , „ 

SET MODE [N01DYNAMIC command, 9-6, 9-id, 

CD-181 rnlR1 

SET MODE [NO]G_FLOAT command, CD-181 


SET MODE [N 01 INTERRUPT command, 14-6, 

CD - 182 , 19 s 

SET MODE [N01KEYPAD command, 12-8, 

CD-182, A-l 1R o 

SET MODE [N01LINE command, CD-182 
SET MODE [NOIOPERANDS command, 8-10, 

" CD-183 , „ , 

SET MODE [N01SCREEN command, ll-i, 

CD - 184 . rn i«4 

SET MODE [NOISCROLL command, CD-184 

SET MODE [N01SEPARATE command, 2-9, 

13-13, CD-185 

SET MODE [NOISYMBOLIC command, 8-id, 

SET MODULE command, 9-6, 9-15, CD-187 
SET OUTPUT command, CD-190 
SET OUTPUT [NO]LOG command, 12-5, cd-isu 
SET OUTPUT [NO]SCREEN_LOG command, 

12-6, CD-190 

SET OUTPUT [NONTERMINAL command, 

" CD-190 

SET OUTPUT [NO] VERIFY command, 12-2, 
CD-190 

SET PROCESS command, 14-7, 14-8, CD-192 
SET PROMPT command, 5-13, CD-196 

multiprocess program, 14-2 
SET RADIX command, 8-10, 18-16, CD 
SET SCOPE command, 9-10, 10-4, 11 b, U », 
11-11, CD-201 

SET SEARCH command, 10-6, CD-205 
SET SOURCE command, 10-2, CD-207 

with concealed rooted-directory logical name, 

CD-208 

SET STEP command, 7-2, 8-19, 10-7, 15- , 
CD-211 m , -o r 

SET STEP SEMANTIC_EVENT command, ld-5 
SET TASK/ACTIVE command, not for 
DECthreads, 16-11, CD-216 
SET TASK command, 16-11, 16 - 23 , CD-215 
SET TERMINAL command, 11-22, CD 218 
SET TRACE command, 7-5, 10-7, 13-19, 15 , 

16-25, 16-29, CD-220 
SET TYPE command, 8-25, CD-228 
SET TYPE/OVERRIDE command, 8-26, CD 228 
SET VECTOR_MODE command, 15-19, tu 
SET WATCH command, 7-11, 10-7, 15-3, 

CD—234 

SET WINDOW command, 11-14, CD-240 
/SET.STATE qualifier, 12-9, CD-66 
/SFPCR qualifier, CD-107 
Shareable images 

See also Modules „ 

CANCEL IMAGE command, 9-13, CD z» 

debugging, 9 11 70 p"n 1 

SET BREAKANTO command, 7-9, CD-ioz 
SET IMAGE command, 9-14, CD-172 
SET STEP INTO command, 7-4, CD-212 
SET TRACE/INTO command, 7-9, CD-224 
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Shareable images (cont’d) 

SET WATCH command, 7-16 
SHOW IMAGE command, 9-13 CD-255 
STEP/INTO command, CD-300 
/SHAREABLE qualifier, 9-H 
Shared linkage images, 4-8 5-7 

,sw Z^S^oV' CD ' 162 ' CD - 224 - 

SHOW t?,? RT - KEY j COmmand ’ 5 ~ 12 ’ CD -242 
bHOW AST command, 13-25 CD-243 

swnw od^ IGN command > 12-2, CD-244 
SHOW BREAK command, 7-5, CD-245 

SHOW CAT??® individual instructions, CD-245 
CD ^2^ command, 5-14, 6-7, 13-20 

SHOW DEFINE command, 12-6 CD-249 
SHOW DISPLAY command, 11-12 CD-250 
SHOW EDITOR c„ mmand , 5^ C D-i 5 2 
SHOW EVENT_FACILITY command 7-10 
16-30, CD-253 

EXITHANDLERS command, 13-25 
CD-254 

^ GE command , 9-13, CD-255 
otiUW KEY command, 12-8, CD-256 

SHOW }^ GUAGE c °mmand, 8-10, CD-259 
btHJW LOG command, 12-6, CD-260 

SHOW MARGINS command, 10-8 CD-261 
SHOW MODE command, CD -262 
SHOW MODULE command, 9—6 9—15 CD orq 
SHOW OUTPUT command, 12-2,12-6 CD~-266 

SHOWRADTX SS C ° mmand ’ 14 ~ 3 ’ 15-2, CD-267 
SHOW RADIX command, 8-10, CD-272 

SHOW SCOPE command, 9-11, CD-273 

SHOW SEARCH command, 10-7 CD-275 

SHOW SELECT command, 11-21 CD-276 

SHOW SOURCE command, 10-2, CD-278 

SHOW STACK command, 13-21 CD-280 

SHOW STEP command, 7-3, CD-283 

SHOW SYMBOL command, 9-8 16-28 CD 284 

s s K ?™ B0L ™ FINEli — 28 i^- 284 

SHOW TASK command, 16-13, 16-16 CD-287 

SHOW TRACF NAL C ° mmand ’ n ~ 23 ’ CD-290 
SHOW TRACE command, 7-5, CD-291 

SHOW d i ying individua l instructions, CD-291 
SHOW TYPE command, 8-26, CD-293 

SHOW VECTOR_MODE command 15-19 
CD-294 

SHOW WATCH command, 7-13 CD-295 
SHOW WINDOW command, 11-15 CD-296 

S/in button, 1-9, 3-8 
/SIZE qualifier, CD-90 
Slash (/) 

division operator, B-8 


SMG$DEFAULT_CHARACTER_SET logical name, 

SMG$ logical name 

debugging screen-oriented program, 13-13 
Source code 

See Source display 
Source directory 

displaying, 10-2, CD-278 
search list, 10-2, CD-34, CD-207 
Source display, 3-1, 6-3, 10-1, 11-1 
discrepancies in, 3-2, 3-4, 11-4, 13-1 
display kind, 11-18 

EXAMINE/SOURCE command, 10-4 11-6 
11-18 ’ ’ 

for routine on call stack, 3-23, 11-6 CD-201 
line-oriented, 10-3 
main window, 1-5 
margins in, 10-8, CD-261 
multiprocess program, 14-15 
not available, 3-4, 6-4, 6-5, 10-1 11-4 
CD-207 

optimized code, 3-2, 5-5, 11-7, 13-1 
SEARCH command, 10-5, CD-148 
SET BREAK command, 10-7 
SET SCOPE/CURRENT command, 11-6 
CD-201 

SET STEP command, 10-7, CD-211 
SET TRACE command, 10-7 
SET WATCH command, 10-7 
source browser, 3-2, 3-4 
SRC, predefined, 11-4 
STEP command, 10-7 
TYPE command, 10-3, CD-310 
Source file 

correct version of, CD-207 
Source files 

See also Source display 

correct version of, CD-207, CD-278 

defined, 10-2 

file specification, 10-2 

location, 3-4, 10-2, CD-34, CD-207 CD-278 
not available, 3-4, 10-2, CD-207 
Source lines 

See also Source display 
breakpoint on, 3-8, 7-6 
not available, 3-4, 6-4, 10-1 
tracepoint on, 7-6 

/SOURCE qualifier, 10-4, 10-7, 11-6 11-21 

cS2% C ?"i° 3 7 6l CD " 153 ’ CD ~ 162 ’’ CD -^ 4 ’ 

Source window 

See also Source display 
%SOURCE_SCOPE, 11-6, ll-i 8 
SPAWN command, 5-12, CD-297 
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SPAWN/NOWAIT command and Kept Debugger, 

CD-298 

%SP built-in symbol, 8-22, B-4 
Split-lifetime variables, 13-9 
SRC, source display, screen mode, 11-4 
S/ret button, 1-9, 3-8 
SS$_DEBUG condition, 6-2, B-l 
SSI and static watchpoints, CD-237 

Stack 

See also Call stack, Scope 
Stack corruption, effect of, 13-19 
Stack pointer (SP), 8-22, B-4 
Stack variables, 3-22, 7-14, 8-1 
Starting debugger, 2-6, 5-7, 14-2, 14-1 
Starting kept debugger, 2-1 

$START_ALIGN_FAULT_REPORT routine and 

SET BREAK/UNALIGNED DATA, CD 164 
/START_POSITION qualifier, CD-168 
/STATE qualifier, 12-9, CD-75, CD 174, ’ 

CD-288 

/STATIC qualifier, CD-235 
Static variables, 3-22, 7-14, 8-1 
Static watchpoints and ASTs, CL) 16 ' 

Static watchpoints and system service calls, 
CD-237 

/STATISTICS qualifier, CD-288 
STEP button, 1-9, 3-7 
STEP command, 7 - 2 , 10-7, CD-299 
and instruction-level debugging, 8-19 
displaying default qualifiers for, CD-28d 
multiprocess program, 14-6 
setting default qualifiers for, CD-211 
vectorized program, 15-3 
STEP/OVER command and Fortran RTL rou ines, 

13 - 18 , 1Q « 

STEP/SEMANTIC_EVENT command, 13-b, 

CD-303 

Stop button, 1-9, 2-6 
/STRING qualifier, 10-6, CD-149 
String types, 8-16, 8-27 
Structure type 
See Record type 
Successor 

See Logical successor 
/SUFFIX qualifier, 14-16, CD-26, 

CD-119, CD-122, CD-134, CD-144, CD-147, 
CD-153, CD-196, CD-250 
Symbolic mode, 8-13, CD-185 
/SYMBOLIC qualifier, 8-13, CD-lOH 
Symbolize 

address, CD—306 
register, CD—306 

SYMBOLIZE command, 7-8, 8-13, CD-306 
Symbolizing 

address, 7-8, 8-13 
register, 8-13 
vector register, 15—1 


Symbol records 
See Symbols 
Symbols 

See also DST, GST, RST, Scope 

ambiguity, resolving, 9-7 

built-in, 6-2, B-3 

compiler generated type, 8-4 

defining, 12-6, CD-63 

displaying, 9-8, 12-6, CD-63, CD-284 

global, 9-3, 9-10 

image setting, 9-13 

label, 7-6, 9-1 

line number, 7-7, 9-1 

local, 3-22, 9-3 

module setting, 9-5 

not in symbol table, 9—5, 9—14 

not unique, 3—23, 9—8 

overloaded, 16—28 

relation to address expression, 8-4 

relation to path name, 9-8 

resolving ambiguities, 3-23 

search based'orTcall stack, 3-23, 9-11, CD-201 
search conventions, 7-7, 9-7, CD 202 
SET SCOPE command, 9-10, CD-201 
shareable image, 9-13 
SHOW SYMBOL command, 9-8 
symbolic mode, 8-13, CD-185 
traceback information, 9-3 
universal, 9-3, 9-5, 9-11, 9-15 
variable, 7-11, 8-1, 8-14, 9-1 
vector register, 15-1 
Symbol tables 

See DST, GST, RST 

Synchronization rn 9 oo 

debugging vectorized program, 15-19, 

CD-294, CD-308 

delivery of vector exception, 15-19, 15-22 
SET VECTOR_MODE command, 15-19, 

CD-232 , ir IQ 

SHOW VECTOR_MODE command, 15-iy, 

CD—294 

SYNCHRONIZE VECTOR_MODE command, 
15-19, CD-308 

System management 

for multiprocess debugging, 

/SYSTEM qualifier, 7-9, CD-162, CD-224, 

CD-301 . . . 

System service calls and static watchpoints, 

CD—237 

System service interception and /DEBUG, 5-7 
System space 

SET BREAK command, CD-162 
SET STEP command, CD-213 
SET TRACE command, CD-224 
STEP command, CD—301 
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/S_FLOAT qualifier, CD-79, CD-107 


%TASK built-in symbol 

See Task ID 

Task ID, 3-27, 16-7, 16-13, 16-15, 16-16, 16-20 
Tasking (multithread) programs 
active task, 3-27, 16-11 
changing task characteristics, 3-28 16-23 
comparison of task and DECthreads 
terminology, 16-2 

controlling and monitoring execution, 16-25 

controlling task switching, 16-24 

deadlock condition, 16-32 

debugging, 3-26, 16-1 

displaying task information, 3-27, 16-16 

environment task, 16-7 

event facility, 16-29 

eventpoints, 16-25 

monitoring events, 16-29 

obtaining priority of task or thread, 16-16, 

16—20 

predefined breakpoint, 16-31 

sample Ada program for debugging, 16-6 

sample C program for debugging, 16-2 

T C^M7o' -FACILITY COmmand ’ 16 -30, 

SET TASK command, 16-23, CD-215 
setting breakpoint, 16-25 

setting priority of task or thread, 3-28, 16-23, 

16—32 , 

setting time-slice value, 16—25 
setting tracepoint, 16-25 
setting watchpoint, 16-25 

SH °CD-253 NT ~ FACILITY COmmand ’ 16-30, 

SHOW TASK command, 16-16, CD-287 
specifying task body, 16-12 

specifying task or thread, 16-11 

stack checking, 16-33 

state of task or thread, 3-27, 16-16, 16-20 

substate °f task or thread, 3-27, 16-16, 16-20 

task built-in symbols, 16-14 

task event, 16-29 

task ID, 16-7, 16-13, 16-15, 16-16, 16-20 
task object, 16-12 
visible task, 16-11 
Tasking view, 1-10 
Tasking View, 3-27 

SL K ‘S'"' 16_I3, CD_79 ' CD - ios - cd - 131 

See also Tasking (multithread) programs 
Task state, 3-27, 16-16, 16-20 
Task substate, 3-27, 16-16, 16-20 


Task switching, 16-24, 16-27 
$TASK_BODY, 16-13,16-26 

(TEMPORARY qualifier, CD-163, CD-224, 
vD-235 
Terminals 

for debugger input/output, separate, 13-13, 
CD—185 

using DECterm window, 2-9 
Terminal screen size 
See Screen size 

/TERMINATE qualifier, 12 - 8 , CD-66 
/TERMINATING qualifier, 14-13 CD-10 CD 
Cim CD-37, cwk. CD^ST 13 ’ 

Termination 

debugging session, 14-10, CD-114, CD-135 
multiprocess program, 14-10, 14-13 
Terminations 

debugging session, 2-6, 5-11 
execution of handlers at, 13-25 
program, 2-5 
programs, 5-10 
Text display 

customizing font for, 3-37 
Text selection 

language sensitive, 3-14, 3-37 
Thread 

See Tasking (multithread) programs 

/TMASK LIC ?fi qUalifier ’ 16 ~ 25, ° D ~ 216 ’ CD ~ 288 
/TMASK qualifier, 15-13, CD-108 

/TOP qualifier, CD-147 

Traceback 

compiler option, 9-3 
link option, 5-6, 9-4 
SHOW CALLS display, 6—7 
/TRACEBACK qualifier, 5-7, 9-4, 9-5 
shareable image, 9-12 
Tracepoints 
action, 7-9 

activating, 2-5, 7-11, CD-12 
canceling, 7-11, CD-37 
conditional, 7-9 
deactivating, 7-11, CD-56 
defined, 7-5 

delayed triggering of, 7-9, CD-221 

displaying, 7-5, CD-291 

DO clause, 7-9 

exception, 13-19, CD-220 

in tasking (multithread) program, 16-25 

on activation (multiprocess program), 14-13 

on label, 7-6 

on routine, 7-6 

on source line, 7-6 

on task event, 16-29 

on termination (image exit), 14—13 

on vector instruction, 15-3 

predefined, 14-13 
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Tracepoints (cont’d) 

saving when rerunning program, 2-5, 5-11 
saving with RERUN command, 5-11, CU-i<5, 
CD-57, CD-140 
setting, 7-5, CD-220 
source display at, 10-7 
WHEN clause, 7-9 
Transfer address, 5-7, 13-15 

Translated images, 13 - 26 > 44 ' 4 Q1 ,, 

TYPE command, 10-3, 11-6, CD 310 
/TYPE qualifier, 8-28, CD-79, CD-I , 

^ peS • ft 4 8 25 

address expression, 8-4, 8-40 

array, 3-15, 3-18, 8-16 

ASCII string, 8-16, 8-27 

compiler generated, 8-4, 8-14 

conversion, numeric, 8-7 

current, 8-25, CD-228, CD-293 

displaying, 8-26, CD-293 

instruction, 8-19 

integer 3—15, 8—15, 8—27 

override, 8-26, CD-40, CD-228, CD-293 

pointer, 3-20, 8-18 

real, 8-15 

record, 3-18, 8-17 

SET TYPE command, 8-25, CD-228 

structure, 3-18, 8-17 

symbolic address expression 8-4 

/TYPE qualifier, 8-28, CD-79, CD 109, 

CD-285 

vector register, 15-6 
/T_FLOAT qualifier, CD-79, CD-108 

U____ 

/UNALIGNED_DATA qualifier, CD-10, CD 24, 

CD-55, CD-163 
Universal symbols 
See Symbols 

/UP qualifier, CD-H9, CD-134 'CD-147 
/USER qualifier, CD-10, CID- 13 , CD 21, 

CD-38, CD-55, CD-57, CD-245, CD 29 
/USE_CLAUSE qualifier, CD-285 


%VAL built-in symbol, CD-16 

/VALUE qualifier, 12-6, CD-62 
Variable names 

address expression, 8-7 
DEPOSIT command, 8-3 
EXAMINE command, 8-2 
language expression, 8-6 
SET WATCH command, 7-11 
Variables 

as override type, 8-28 
automatic, 3-20, 3-22, 8-1 


Variables (cont’d) 

changing value of, 3-21, 8-3, 8-1 
depositing into, 3-21, 8-3, 8-14 
displaying value of, 3-15, 8-2, 8-1 
examining, 3-15, 8-2, 8-14 
global section, 14-16 
monitoring, 3-18, CD-129 
nonstatic, 3—22, 7—14, 8-1 
optimized code, 3-21, 13-1 
register, 3-22, 7-14, 8-1 
selecting name from window, 3-14 
stack local, 3—22, 7—14, 8—1 
static, 3-22, 7-14 
uninitialized, 3—21, 8—1 
watchpoint, 3-20, 7-11, 14-16 

VAXstations 

See Workstations 

VAX Vector Instruction Emulation Facility 

SeeWIEF . _ 

VAX Vector Instruction Emulation Facility 

(WIEF) 

SHOW PROCESS/FULL command, 15-2 
%VCR built-in symbol 
See VCR 

VCRs (vector count registers), 15-4, rs 
Vector count register 
See VCR 
Vector exceptions 

delivery of, 15-19, 15-22 

^activate^rea^vectorjnstruction 

ACTIVATE TRAC^ECTORJNSTRUCTION 
CANCELBREA^ECTORJNSTRUCTION 

can“t^ce/^c C torjnstruction 
command, 15—3, CD—38 
DEACTIVATE BREAK/VECTOR_ 

INSTRUCTION command, CD-55 
DEACTIVATE TRACE/VECTOR_ 

INSTRUCTION command, CD-57 
delivery of vector exception, 15-19, 15-22 
depositing, 15-12 
displaying, 15-8 

EXAMINE/OPERANDS command, 15-9 
examining, 15-9 
masked operation, 15-9, 15-14 
operand, 15-9 

SETBREA^VECTORJNSTRUCTION 

SET^TEPVECTOR^INSTRUCTION command, 
15-3, CD-213 

SET TRACE/VECTORJNSTRUCTION 

command, 15—3, CD—225 
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Vector instructions (cont’d) 

STEP/V^:ctoR_INSTRUCTION command, 

15-3, CD-301 
Vectorized programs 

CA LIV[N0 ] SAVE_ V E CT °R_STA TE command, 

controlling and monitoring execution, 15-2 
debugging, 15-1 

delivery of vector exception, 15-19, 15-22 
depositing into vector register, 15-4, 15-6 
depositing vector instruction, 15-12 
EXAMINE/FMASK command, 15-13 
EXAMINE/OPERANDS command, 15 - 9 , 

EXAMINE/TMASK command, 15-13 
examining vector instruction, 15-9 
examining vector register, 15-4, 15_6 
masked operation, 15-5, 15-9, 15-13 
obtaining information about, 15-2 
setting breakpoint, 15-3 
setting tracepoint, 15-3 
setting watchpoint, 15-3 

SET VECTOR_MODE command, 15 - 19 , 

CD— 232 

PROCESS/FULL command, 15-2 
“f°R- M0DE command, 15-19, 


specifying vector register, 15-4 
SYNCHKONIZE VECTOR_MODE command, 
15-19, CD-308 

synchronizing scalar and vector processors, 
15—19 

VO to V15, 15-6 
VCR, 15-4 
VLR, 15-4 

VMR, 15-5,15-9,15-13 
Vector length register 
See VLR 

Vector mask register 
See VMR 
Vector mode 


SET VECTOR_MODE [NO]SYNCHRONIZED 
command, 15-19 

SVNCHROMIZE VECTOR_MODE command, 

15-19 

Vector registers 
See also Registers 
built-in symbol, 15-4, B-4 
composite address expression, 15-16 
depositing into, 15-4, 15-6 
display, screen mode, 11-10, 11-16 15-22 
examining, 15-4, 15-6 
scope, 15-1 
VO to V15, 15-6, B-4 
VCR, 15-4, B-4 
VLR, 15-4, B-4 
VMR, 15-5, 15-9, 15-13, B-4 


Vector registers (cont’d) 
watchpoint, 15-3 

A^ECTOR_ inst R uction qualifier 15 3 

CD 10 , CD-13, CD-24, CD-38, CD -55 

CD -57, CD-163, CD-225, CD-301 
Views 

See also Windows 
Breakpoint, 1-10, 3-10 
Instruction, 1-10, 3-26 
Monitor, 1-10, 3-18 
Register, 1-10, 3-25 
startup configuration, 3-29 
Tasking, 1-10, 3-27 
Virtual memory address 
See Addresses 

Visible processes, 14-2, 14 - 3 , u 3 

Alible qualifier, 16-11, CD-193, CD-216, 
OD—268 

%VISIBLE_PROCESS built-in symbol 14-12 
%VISIBLE_TASK built-in symbol, 16-11 16-15 
%VLR built-in symbol 


See VLR 

VLRs (vector length registers), 15-4, B-4 
%VMR built-in symbol 
See VMR 

VMRs (vector mask registers), 15-4 15-5 is o 
15-13, B-4 ’ ’ 


w 

/WAIT qualifier, CD-297 

Watchpoints, 3-20 

activating, 2-5, 3-20, 7-13, CD-14 
aggregate, 7-13, 15-3 
canceling, 7-13, CD-41 
deactivating, 3-20, 7-13, CD-58 
defined, 3-20, 7-11 
displaying, 3-20, 7-13, CD-295 
effect on execution speed, 7—15 
global section, 14-16 
in multiprocess program, 14-16 
in tasking (multithread) program, 16-25 
nonstatic variable, 3-20, 7-14 
register, 3-20, 7-14 

saving when rerunning program, 2-5 5-11 
saving with RERUN command, 5-11 CD-14 
CD-58, CD-140 
setting, 3-20, 7-11, CD-234 
shareable image, 7-16 
source display at, 10-7 
static variable, 3-20, 7-14 
vector register, 15-3 
Watchpoints, static, and ASTs, CD-237 
WHEN clause, 7-9, CD-4 
WHILE command, 12-10, CD-312 
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% WIDTH built-in symbol, 11-23 
/WIDTH qualifier, 11-22, CD-218 

Window . 

for debugger command interlace 
VWS window, CD—185 

screen-mode 

creating definition for, CD-240 
deleting definition of, CD-42 
identifying, CD-296 
predefined, CD-296 


See also Command interface, DECwindows 
interface, Views 

for debugger command interface, 1 

DECwindows Motif DECterm window, 2-9 

VWS window, 13-13 
for entering debugger commands, 1-15 


instruction, 3—26 

optional views window, 1-10 


screen-mode 

creating definition for, 11—1 
defined, 11-2 

deleting definition of, 11-15 
identifying, 11-15 
predefined, 11-24 
specifying, 11-14 


source, 1-5 

screen-mode, 11—4 


startup configuration, 15 

/WORD qualifier, CD-79, CD-109, CD 

Workstation . , m7Q rn _r 

debugger commands when using > 
debugging screen-oriented program 

using separate VWS window, CD-185 
popping debugger window when using VW , 
CD-197 . , 

separate debugger terminal-emulator window 
using VWS, CD-185 R 

terminal emulator screen size, CD-218 

Workstations Q Q 

debugging DECwindows Motif application, 2 
debugging screen-oriented program 

using separate DECterm window, 2-y 
using separate VWS window, 13-13 
separate, for debugger DECwindows Motif 
interface, 2-8 . 

separate debugger terminal-emulator window 

using DECwindows Motif (DECterm), 2 9 

using VWS, 13-13 
terminal emulator screen size, 11-22 


X __ 

/X_FLOAT qualifier, CD-79, CD-109 
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